[edk2-InfSpecification PATCH] Clarify statement on package ordering

[edk2-InfSpecification PATCH] Clarify statement on package ordering

[Laszlo Ersek]

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
+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
-- 
2.19.1.3.g30247aa5d201

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

[Philippe Mathieu-Daudé]

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
> 

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

[Michael D Kinney]

Reviewed-by: Michael D Kinney <michael.d.kinney@intel.com>

Mike

> -----Original Message-----
> From: devel@edk2.groups.io <devel@edk2.groups.io> On
> Behalf Of Laszlo Ersek
> Sent: Wednesday, June 3, 2020 11:05 AM
> To: edk2-devel-groups-io <devel@edk2.groups.io>
> Cc: Andrew Fish <afish@apple.com>; Leif Lindholm
> <leif@nuviainc.com>; Kinney, Michael D
> <michael.d.kinney@intel.com>; Pankaj Bansal
> <pankaj.bansal@oss.nxp.com>; Philippe Mathieu-Daudé
> <philmd@redhat.com>
> Subject: [edk2-devel] [edk2-InfSpecification PATCH]
> Clarify statement on package ordering
> 
> 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
> +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
> --
> 2.19.1.3.g30247aa5d201
> 
> 
> 

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

[Laszlo Ersek]

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

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

[Laszlo Ersek]

On 06/03/20 20:04, 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
> +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
> 

Pushed as commit 1e0698a2e33e.

Thanks!
Laszlo