[yocto] Requesting information on some variables

[Rifenbark, Scott M]

This is helpful... thanks Paul.

-----Original Message-----
From: Paul Eggleton [mailto:paul.eggleton at linux.intel.com] 
Sent: Wednesday, October 17, 2012 8:59 AM
To: Rifenbark, Scott M
Cc: yocto at yoctoproject.org
Subject: Re: [yocto] Requesting information on some variables

On Wednesday 17 October 2012 15:32:40 Rifenbark, Scott M wrote:
> There is a bug (https://bugzilla.yoctoproject.org/show_bug.cgi?id=3292)
> stating that we need better documentation describing how DISTRO_FEATURES,
> COMMON_FEATURES, and MACHINE_FEATURES actually affect the build.  I don't
> know anything about these variables beyond what is in the reference manual:
> 
> http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#va
> r-DISTRO_FEATURES
> http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#v
> ar-MACHINE_FEATURES (no current entry for  COMMON_FEATURES)
> 
> Can anyone provide additional information for these three variables and how
> they interact with the build system and with one another?

Looking at the bug report I'm guessing Darren was looking at the current 
version of the documentation prior to adding a link to the section that lists 
DISTRO_FEATURES options (which only got added recently). However that list is 
incomplete and even then it does not explain how you would determine what the 
actual effect of adding or removing a feature would be.

I think Darren's suggestion of using "git grep" to find the actual effect is 
good, after some preamble that mentions we use the "base_contains" function in 
various recipes and configuration files in order to change behaviour based on 
the presence or absence of features, giving at least one example from the 
current metadata.

Some explanation of how these variables relate to eachother:

* DISTRO_FEATURES is used to enable/disable software features (some of which 
are related to hardware feature support). This is set in the distro .conf file.

* MACHINE_FEATURES describes what hardware features a specific machine 
supports. It is set in the machine .conf file.

* COMBINED_FEATURES lists features both enabled by DISTRO_FEATURES and 
supported by the hardware as declared by MACHINE_FEATURES. It is set 
automatically by the build system.

The COMBINED_FEATURES mechanism allows a BSP to declare that a piece of 
hardware supports a feature, but a person building a distro (or OS) to decide 
that they don't want to support the feature; thus the feature only gets 
enabled in the software if it appears on in both places.

Cheers,
Paul

 
> Thanks,
> Scott
> 
> 
> Bug 3292
> 
> The documentation for the following variables:
> 
> DISTRO_FEATURES
> COMMON_FEATURES
> MACHINE_FEATURES
> 
> is inadequate to instruct would-be users of how changes will impact the
> system.
> 
> These variables combine to determine various aspects of how images and
> packages are built. They impact RDEPENDS of various packagegroups, impact
> the way live images are built, and certainly others. MACHINE_FEATURES as a
> documented list of values, DISTRO_FEATURES does not. I do not see
> COMMON_FEATURES listed at all.
> 
> A discussion of how these interrelate and how someone can discover the exact
> impact from the sources would be useful. For example, using "git grep
> 'contains.*MACHINE_FEATURES.*<FEATURE>'" to discover how the build is
> impacted would be a useful addition.
> 
> It isn't practical to define the dependency chains in the documentation, but
> providing the user with the background and tools to discover them seems
> appropriate.
> 
> 
> Scott Rifenbark
> Intel Corporation
> Yocto Project Documentation
> 503.712.2702
> 503.341.0418 (cell)
-- 

Paul Eggleton
Intel Open Source Technology Centre