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

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

On 06/02/20 15:37, Pankaj Bansal (OSS) wrote:
> 
> 
>> -----Original Message-----
>> From: Laszlo Ersek <lersek@redhat.com>
>> Sent: Tuesday, June 2, 2020 7:00 PM
>> To: Leif Lindholm <leif@nuviainc.com>; devel@edk2.groups.io;
>> michael.d.kinney@intel.com
>> Cc: Andrew Fish <afish@apple.com>; Pankaj Bansal (OSS)
>> <pankaj.bansal@oss.nxp.com>
>> Subject: Re: [edk2-devel] [PATCH edk2-InfSpecification] Drop statement on
>> package ordering
>>
>> 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.
>> """
> 
> Nicely summed up! it is much clearer now for anyone like me who wants to port edk2 for his platform.
> one more suggestion. should this be mentioned along with above explaination:
> "whenever possible use lexicographically ascending order"

I'd love that, but it's really just a policy question that I prefer.

If we tried to elevate my preference to official edk2 spec level, it
could run into opposition (like any other proposal -- so that would be
just fine, per se!). I just wouldn't like to delay the more important
clarification with a discussion around my preference.

So minimally, that would take a two-part patch series, and even so the
second patch would likely have to be marked RFC. I think we can simply
postpone the official speccing of the lexicographical sorting idea
(indefinitely, even).

Thanks
Laszlo