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

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

On 06/04/20 08:25, Philippe Mathieu-Daudé wrote:
> 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 ...".

https://en.wiktionary.org/wiki/help#Etymology_2

"He helped his grandfather cook breakfast."
"The white paint on the walls helps make the room look brighter."

"""
Usage notes

In uses 1, 2 and 3, this is a catenative verb that takes the /to
infinitive/. It can also take the bare infinitive with no change in meaning.
"""

I tend to use the bare infinitive with "help".

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

Thanks!

Laszlo

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