public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
From: "Leif Lindholm" <leif@nuviainc.com>
To: devel@edk2.groups.io, lersek@redhat.com
Cc: michael.d.kinney@intel.com, Andrew Fish <afish@apple.com>,
	Pankaj Bansal <pankaj.bansal@oss.nxp.com>
Subject: Re: [edk2-devel] [PATCH edk2-InfSpecification] Drop statement on package ordering
Date: Wed, 3 Jun 2020 12:44:04 +0100	[thread overview]
Message-ID: <20200603114404.GQ28566@vanye> (raw)
In-Reply-To: <bc93bcac-434b-17f0-4525-3f73fdff470c@redhat.com>

On Tue, Jun 02, 2020 at 18:20:26 +0200, Laszlo Ersek wrote:
> On 06/02/20 16:20, Leif Lindholm wrote:
> > On Tue, Jun 02, 2020 at 15:29:55 +0200, Laszlo Ersek wrote:
> >> I have not been aware of the header name collision scenario (nor that
> >> the [Packages] ordering was supposed to work around such issues).
> > 
> > Nor had I...
> > 
> >> 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.
> >> """
> > 
> > Could I suggest striking:
> > " -- 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"?
> 
> I'm sad; that's the part I like the most! ;) That describes the actual
> use case (I'm a fan of use case details in commit messages too).
> 
> Anyway, I don't insist...
> 
> > 
> > This document specifies a file format, not automatically edk2-related.
> 
> I disagree with this specific statement; the INF spec says "edk2" in the
> *name*. It's called "edk2 INF specification".
> 
> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Specifications
> 
> "This page contains the released versions of the EDK II Specifications
> published using Gitbook."
> 
> https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Specifications#inf
> 
> "This document describes the EDK II build information (INF) file format."
> 
> The following link doesn't seem to load at the moment:
> 
> https://edk2-docs.gitbooks.io/edk-ii-inf-specification/content/v/release/1.27/
> 
> but checking the source in the git repo
> <https://github.com/tianocore-docs/edk2-InfSpecification>, the actual
> text seems to say "EDK II Module Information (INF) File Specification".
> 
> The whole feature is related to out-of-tree INF files (where header file
> name collisions cannot be easily detected).

My wording "edk2-related" was imprecise to the level of being
incorrect, apologies for adding confusion.

My intended point wast that here is nothing specific about colliding
with headers in the edk2 repository. This aspect relates to *all*
different repos used by a specific platform. (And given how much magic
the EDK2 build system looks to a newcomer anyway...)

> > I think we're reaching a point where a major documentation overhaul is
> > necessary. I had already been reflecting on how the coding style
> > document encompasses more than coding style (at one point it explains
> > how while() loops are different from do{}while() loops). And we
> > recently had that conversation around struct assignments which some
> > maintainers claim are banned, but which is not mentioned in that
> > document.
> > 
> > Not trying to resolve that issue *now*, just reflecting on how some
> > things have been added to these documents historically to deal with a
> > specific issue, and ended up confusing things as improved development
> > practices have made the original problem go away.
> > 
> > So with the edk2 refences removed, I like your new wording.
> 
> OK -- I won't let "perfect" get in the way of "good" :)

So, umm, given that the entire actual content of the patch would now
be written by you - could you submit possibly your own patch, and I'll
abandon this one?

I'd be happy with (or frankly, without :) a Suggested-by.

Regards,

Leif

> Thanks!
> Laszlo
> 
> 
> 
> 

  reply	other threads:[~2020-06-03 11:44 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-05-29 14:02 [PATCH edk2-InfSpecification] Drop statement on package ordering Leif Lindholm
2020-05-31 22:19 ` Michael D Kinney
2020-05-31 22:43   ` [edk2-devel] " Leif Lindholm
2020-06-01  3:39     ` Pankaj Bansal
2020-06-01  5:15       ` Michael D Kinney
2020-06-01  7:01         ` Pankaj Bansal
2020-06-01 15:31           ` Michael D Kinney
2020-06-02 13:29     ` Laszlo Ersek
2020-06-02 13:37       ` Pankaj Bansal
2020-06-02 14:22         ` Leif Lindholm
2020-06-02 16:11         ` Laszlo Ersek
2020-06-03  3:12           ` Pankaj Bansal
2020-06-02 14:20       ` Leif Lindholm
2020-06-02 16:20         ` Laszlo Ersek
2020-06-03 11:44           ` Leif Lindholm [this message]
2020-06-03 13:43             ` Laszlo Ersek
2020-06-03  3:33 ` Andrew Fish
     [not found] ` <1614EB3F428C08F5.21938@groups.io>
2020-06-03  3:41   ` [edk2-devel] " Andrew Fish

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-list from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20200603114404.GQ28566@vanye \
    --to=devel@edk2.groups.io \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox