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

["Philippe Mathieu-Daudé" <philmd@redhat.com>]

Hi Laszlo,

On 6/3/20 8:04 PM, Laszlo Ersek wrote:
> The description of [Packages] sections states,
> 
>> 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.
> 
> Clarify that the listing order in [Packages] is only relevant for
> resolving header file name collisions between packages. Mention that such
> collisions are generally not expected. Remove the example about MdePkg and
> MdeModulePkg, because both of those are in edk2, and we'd certainly
> address a collision between those packages explicitly (e.g., by renaming
> one of the subject header files).
> 
> Cc: Andrew Fish <afish@apple.com>
> Cc: Leif Lindholm <leif@nuviainc.com>
> Cc: Michael Kinney <michael.d.kinney@intel.com>
> Cc: Pankaj Bansal <pankaj.bansal@oss.nxp.com>
> Cc: Philippe Mathieu-Daudé <philmd@redhat.com>
> Suggested-by: Leif Lindholm <leif@nuviainc.com>
> Signed-off-by: Laszlo Ersek <lersek@redhat.com>
> ---
> 
> Notes:
>     (1) This is the one shot I'm willing to take. If it's not accepted,
>         someone else will have to work on this. (I only meant to provide
>         some wording ideas under Leif's patch; I don't have time for
>         multiple iterations on an actual INF spec patch.)
>     
>     (2) Repo:   https://github.com/lersek/edk2-InfSpecification
>         Branch: pkgs_order
>     
>     (3) Rendered view:
>     
>         https://lersek.gitbook.io/laszlo-s-fork-of-the-edk-ii-module-information-inf/v/pkgs_order/3_edk_ii_inf_file_format/37_-packages-_sections#summary
> 
>  3_edk_ii_inf_file_format/37_[packages]_sections.md | 15 ++++++++++-----
>  1 file changed, 10 insertions(+), 5 deletions(-)
> 
> diff --git a/3_edk_ii_inf_file_format/37_[packages]_sections.md b/3_edk_ii_inf_file_format/37_[packages]_sections.md
> index 17a8d91ec8aa..6f8b8b6dd250 100644
> --- a/3_edk_ii_inf_file_format/37_[packages]_sections.md
> +++ b/3_edk_ii_inf_file_format/37_[packages]_sections.md
> @@ -42,11 +42,16 @@ Defines the `[Packages]` section tag that is used in EDK II module INF files.
>  Each entry in this section contains a directory name, forward slash character
>  and the name of the DEC file contained in the directory name.
>  
> -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. If there
> -are PCDs listed in the generated "As Built" INF, the packages that declare any
> -PCDs must be listed in this section.
> +The order in which packages are listed may be relevant. Said order specifies in
> +what order include path statements are generated for a compiler. This may help

I'm obviously not a native English speaker, but I'd have use "may help
[to] resolve ...".

Regardless:
Reviewed-by: Philippe Mathieu-Daude <philmd@redhat.com>

> +resolve header file name collisions between packages (although such collisions
> +are normally not expected). 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.
> +
> +If there are PCDs listed in the generated "As Built" INF, the packages that
> +declare any PCDs must be listed in this section.
>  
>  Each package filename must be listed only once per section. Package filenames
>  listed in architectural sections are not permitted to be listed in the common
>