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

["Michael D Kinney" <michael.d.kinney@intel.com>]

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