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

["Pankaj Bansal" <pankaj.bansal@nxp.com>]

> -----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"

> 
> Thanks
> Laszlo