Re: [edk2-devel] [PATCH edk2-InfSpecification] Drop statement on package ordering

["Laszlo Ersek" <lersek@redhat.com>]

On 06/01/20 00:43, Leif Lindholm wrote:
> Hi Mike,
> 
> Ok, I'm happy to hear that.
> 
> I agree that the overriding behaviour is useful, and it would be good
> to document it. The problem is that the current wording does not say
> that (in a way that is useful to anyone who does not already know what
> it means). And the MdePkg/MdeModulePkg example sounds positively
> horrific when interpreted in this light.
> 
> Clearly, my proposed modification is not the right thing to do here.
> 
> The problem with the document implying that the order should reflect
> some sort of hierarchy *apart from when explicitly overriding* is that
> this is asking a human to do the thing that humans are bad at and
> computers are good at. It can't scale where humans are reviewing ports
> that they understand less well than the people contributing them.
> 
> I think we should find a wording that explains the behaviour instead
> of explaining some potential derivative of the behaviour, as well as
> providing a realistic example instead of the MdePkg/MdeModulePkg
> statament.
> 
> My suggestion is to keep it simple: say something like "where there is
> a need to override an include file provided by one package with one
> provided by another package, know that the compiler invocation will
> list the include directories in the same order as the .dec files are
> listed in the .inf".

(since I've been copied)

I have not been aware of the header name collision scenario (nor that
the [Packages] ordering was supposed to work around such issues).

I work strictly with edk2 proper, where a name collision like this can
be detected, and so should be prevented. (Insert yet another argument
why keeping platform code outside of edk2 is a bad idea.) In particular,
a collision between MdePkg and MdeModulePkg would be super bad.

Which now seems to turn out consistent with my general review point that
the [Packages] section, like (almost) all other INF file sections,
should be sorted lexicographically.

How about replacing

"""
Packages must be listed in the order that may be required for specifying
include path statements for a compiler. For example, the MdePkg/MdePkg.dec_
file must be listed before the `MdeModulePkg/MdeModulePkg.dec` file.
"""

with

"""
The order in which packages are listed may be relevant. Said order
specifies in what order include path statements are generated for a
compiler. Normally, header file name collisions are not expected between
packages -- they are forbidden in edk2 proper --, but with a module INF
consuming both edk2-native and out-of-edk2 packages, header file names
may collide. For setting specific include path priorities, the packages
may be listed in matching order in the INF file. Listing a package
earlier will cause a compiler to consider include paths from that
package earlier.
"""

Thanks
Laszlo