[gentoo-pms] Small cleanup of ebuild-functions.tex

[gentoo-pms] Small cleanup of ebuild-functions.tex

[Patrick Lauer]

[-- Attachment #1: Type: Text/Plain, Size: 547 bytes --]

Today on the menu: Making PMS describe the ebuild functions more precisely.

First change: the test phase is only run when enabled. Since PMS doesn't 
document FEATURES yet we can only say "if tests are enabled" instead of being 
more precise. Well, defining FEATURES shouldn't be too hard, but that's for 
another day.

Second change: The phase order for package updates and reinstalls is the same. 
This makes a whole chunk of the listing redundant, so we can collapse it.

3 lines added, 21 removed. Isn't decrufting great?

Have fun,

Patrick

[-- Attachment #2: pms-fix-ebuild-phases.patch --]
[-- Type: text/x-patch, Size: 2145 bytes --]

diff --git a/ebuild-functions.tex b/ebuild-functions.tex
index 11ff216..4e327d1 100644
--- a/ebuild-functions.tex
+++ b/ebuild-functions.tex
@@ -578,7 +578,7 @@ The call order for installing a package is:
 \item \t{src\_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
 \item \t{src\_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table})
 \item \t{src\_compile}
-\item \t{src\_test} (except if \t{RESTRICT=test})
+\item \t{src\_test} (iff tests are enabled, except if \t{RESTRICT=test})
 \item \t{src\_install}
 \item \t{pkg\_preinst}
 \item \t{pkg\_postinst}
@@ -591,7 +591,7 @@ The call order for uninstalling a package is:
 \item \t{pkg\_postrm}
 \end{compactitem}
 
-The call order for reinstalling a package is:
+The call order for reinstalling, upgrading or downgrading a package is:
 
 \begin{compactitem}
 \item \t{pkg\_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
@@ -601,25 +601,7 @@ The call order for reinstalling a package is:
 \item \t{src\_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
 \item \t{src\_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table})
 \item \t{src\_compile}
-\item \t{src\_test} (except if \t{RESTRICT=test})
-\item \t{src\_install}
-\item \t{pkg\_preinst}
-\item \t{pkg\_prerm} for the package being replaced
-\item \t{pkg\_postrm} for the package being replaced
-\item \t{pkg\_postinst}
-\end{compactitem}
-
-The call order for upgrading or downgrading a package is:
-
-\begin{compactitem}
-\item \t{pkg\_pretend} (only for EAPIs listed in table~\ref{tab:pkg-pretend-table}), which is called
-    outside of the normal call order process.
-\item \t{pkg\_setup}
-\item \t{src\_unpack}
-\item \t{src\_prepare} (only for EAPIs listed in table~\ref{tab:src-prepare-table})
-\item \t{src\_configure} (only for EAPIs listed in table~\ref{tab:src-configure-table})
-\item \t{src\_compile}
-\item \t{src\_test} (except if \t{RESTRICT=test})
+\item \t{src\_test} (iff tests are enabled, except if \t{RESTRICT=test})
 \item \t{src\_install}
 \item \t{pkg\_preinst}
 \item \t{pkg\_postinst}

Re: [gentoo-pms] Small cleanup of ebuild-functions.tex

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 1124 bytes --]

On Sun, 20 Sep 2009 17:21:24 +0200
Patrick Lauer <patrick@gentoo.org> wrote:
> First change: the test phase is only run when enabled. Since PMS
> doesn't document FEATURES yet we can only say "if tests are enabled"
> instead of being more precise. Well, defining FEATURES shouldn't be
> too hard, but that's for another day.

Please cross-reference that to the part where we explain that src_test
is run at user option. You might also want to tidy up the language on
that so that the user option part is explained even if kdebuild is
disabled.

> Second change: The phase order for package updates and reinstalls is
> the same. This makes a whole chunk of the listing redundant, so we
> can collapse it.

Actually, this one's a bit of a mess, thanks to Portage making a
non-EAPI-controlled order change that was supposed to go in in EAPI 2
but didn't. If you're updating it, please do so to accurately reflect
both orders that can be and are used.

> 3 lines added, 21 removed. Isn't decrufting great?

Decrufting is only good if what you're doing really is removing cruft...

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-pms] Small cleanup of ebuild-functions.tex

[Patrick Lauer]

On Sunday 20 September 2009 17:37:59 Ciaran McCreesh wrote:
> On Sun, 20 Sep 2009 17:21:24 +0200
> 
> Patrick Lauer <patrick@gentoo.org> wrote:
> > First change: the test phase is only run when enabled. Since PMS
> > doesn't document FEATURES yet we can only say "if tests are enabled"
> > instead of being more precise. Well, defining FEATURES shouldn't be
> > too hard, but that's for another day.
> 
> Please cross-reference that to the part where we explain that src_test
> is run at user option.
I fail to find such a thing in current PMS.

> You might also want to tidy up the language on
> that so that the user option part is explained even if kdebuild is
> disabled.
I suggest we do as you suggested yesterday and remove kdebuild 
unconditionally. That saves hacking around something that cannot be in the 
final version anyway.
> 
> > Second change: The phase order for package updates and reinstalls is
> > the same. This makes a whole chunk of the listing redundant, so we
> > can collapse it.
> 
> Actually, this one's a bit of a mess, thanks to Portage making a
> non-EAPI-controlled order change that was supposed to go in in EAPI 2
> but didn't.
Yeah, messy thing. But as you are well aware there was no sane way to make 
that change EAPI-dependant without causing ambiguous situation and much more 
confusion.

> If you're updating it, please do so to accurately reflect
> both orders that can be and are used.
Any version of portage in use uses the "later" version. Feel free to document 
historic behaviour if you want, but as PMS hasn't documented it before I'd put 
it in the errata section.
 
> > 3 lines added, 21 removed. Isn't decrufting great?
> Decrufting is only good if what you're doing really is removing cruft...
Well, I've started with the simple things. Once we have the big errors fixed 
we can move on to the more interesting changes ...

Re: [gentoo-pms] Small cleanup of ebuild-functions.tex

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 2420 bytes --]

On Sun, 20 Sep 2009 18:21:48 +0200
Patrick Lauer <patrick@gentoo.org> wrote:
> > > First change: the test phase is only run when enabled. Since PMS
> > > doesn't document FEATURES yet we can only say "if tests are
> > > enabled" instead of being more precise. Well, defining FEATURES
> > > shouldn't be too hard, but that's for another day.
> > 
> > Please cross-reference that to the part where we explain that
> > src_test is run at user option.
> I fail to find such a thing in current PMS.

Grep for 'src-test-required', and bear in mind what I said about "so
that the user option part is explained even if kdebuild is disabled".
That language really should be in even if kdebuild is turned off,
especially if we're explicitly stating that src_test is optional.

> > You might also want to tidy up the language on
> > that so that the user option part is explained even if kdebuild is
> > disabled.
> I suggest we do as you suggested yesterday and remove kdebuild 
> unconditionally. That saves hacking around something that cannot be
> in the final version anyway.

I suggest you stop trying to push a political agenda when doing so just
makes life harder for the people who have to use PMS.

> > Actually, this one's a bit of a mess, thanks to Portage making a
> > non-EAPI-controlled order change that was supposed to go in in EAPI
> > 2 but didn't.
> Yeah, messy thing. But as you are well aware there was no sane way to
> make that change EAPI-dependant without causing ambiguous situation
> and much more confusion.

Actually, there was a perfectly clean way of doing it, and Zac even
agreed to do it that way before he went and implemented it
unconditionally. The change was supposed to be going through as part of
EAPI 2.

> > If you're updating it, please do so to accurately reflect
> > both orders that can be and are used.
> Any version of portage in use uses the "later" version.

That's not how the system works. We're supposed to be documenting what
ebuilds may rely upon from compliant package managers. Since there are
compliant package managers that use both behaviours, the
documentation's supposed to reflect that.

> Feel free to document historic behaviour if you want, but as PMS
> hasn't documented it before I'd put it in the errata section.

Doesn't PMS currently document the old way of doing it, not the new way?

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-pms] Small cleanup of ebuild-functions.tex

[Patrick Lauer]

On Sunday 20 September 2009 18:34:12 Ciaran McCreesh wrote:
> On Sun, 20 Sep 2009 18:21:48 +0200
> 
> Patrick Lauer <patrick@gentoo.org> wrote:
> > > > First change: the test phase is only run when enabled. Since PMS
> > > > doesn't document FEATURES yet we can only say "if tests are
> > > > enabled" instead of being more precise. Well, defining FEATURES
> > > > shouldn't be too hard, but that's for another day.
> > >
> > > Please cross-reference that to the part where we explain that
> > > src_test is run at user option.
> >
> > I fail to find such a thing in current PMS.
> 
> Grep for 'src-test-required', and bear in mind what I said about "so
> that the user option part is explained even if kdebuild is disabled".
Oh. That's well hidden and not visible to the normal reader. You naughty boy!

> That language really should be in even if kdebuild is turned off,
> especially if we're explicitly stating that src_test is optional.
Needs to have FEATURES defined first, otherwise we'll be defining a specific 
configuration in abstract generalities. 

> 
> > > You might also want to tidy up the language on
> > > that so that the user option part is explained even if kdebuild is
> > > disabled.
> > I suggest we do as you suggested yesterday and remove kdebuild
> > unconditionally. That saves hacking around something that cannot be
> > in the final version anyway.
> I suggest you stop trying to push a political agenda when doing so just
> makes life harder for the people who have to use PMS.
Uhm what. I thought we had all found an agreement yesterday that having 
kdebuild in PMS was a bad thing. If you keep changing your opinion every day 
there's no way to have a reasonable discussion.


> > > Actually, this one's a bit of a mess, thanks to Portage making a
> > > non-EAPI-controlled order change that was supposed to go in in EAPI
> > > 2 but didn't.
> >
> > Yeah, messy thing. But as you are well aware there was no sane way to
> > make that change EAPI-dependant without causing ambiguous situation
> > and much more confusion.
> 
> Actually, there was a perfectly clean way of doing it, and Zac even
> agreed to do it that way before he went and implemented it
> unconditionally. The change was supposed to be going through as part of
> EAPI 2.
Nah, that makes a huge stinky if you try to upgrade an EAPI0 package with an 
EAPI2 package or vice versa. Then you end up with a dozen potential ways of 
doing it, choose one randomly and hope that was a sane decision.

Having a consistent phase order is the only way to keep things predictable ...

> That's not how the system works. We're supposed to be documenting what
> ebuilds may rely upon from compliant package managers. Since there are
> compliant package managers that use both behaviours, the
> documentation's supposed to reflect that.
Hrm. All versions of all officially supported package managers I can see use 
the "newer" behaviour. So the "old" behaviour might be interesting for 
historical reasons, but anything currently in use is forced to rely on the 
"new" behaviour.

 
> > Feel free to document historic behaviour if you want, but as PMS
> > hasn't documented it before I'd put it in the errata section. 
> Doesn't PMS currently document the old way of doing it, not the new way?
See, that's what happens when you don't document what is actually happening. 
Now you are confused, I'm slightly confused and we can't even discuss basic 
things anymore.

As far as I can tell current PMS documents the new behaviour. At least that's 
the impression I get from comparing older versions of it to the current state 
and looking at previous discussions. Unless I got things backwards again 
because they aren't documented properly.

Either way there's a lot that needs to be done until PMS deserves the S in its 
name, but it's not hopeless. At least we're noticing the things it doesn't 
document or doesn't document correctly quite nicely.

Re: [gentoo-pms] Small cleanup of ebuild-functions.tex

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 3062 bytes --]

On Sun, 20 Sep 2009 18:52:25 +0200
Patrick Lauer <patrick@gentoo.org> wrote:
> > That language really should be in even if kdebuild is turned off,
> > especially if we're explicitly stating that src_test is optional.
>
> Needs to have FEATURES defined first, otherwise we'll be defining a
> specific configuration in abstract generalities. 

We use language like "at user option", without indicating what that
user option is.

> > I suggest you stop trying to push a political agenda when doing so
> > just makes life harder for the people who have to use PMS.
>
> Uhm what. I thought we had all found an agreement yesterday that
> having kdebuild in PMS was a bad thing. If you keep changing your
> opinion every day there's no way to have a reasonable discussion.

Please point me to where I (who am part of 'all') agreed that.

> > Actually, there was a perfectly clean way of doing it, and Zac even
> > agreed to do it that way before he went and implemented it
> > unconditionally. The change was supposed to be going through as
> > part of EAPI 2.
> Nah, that makes a huge stinky if you try to upgrade an EAPI0 package
> with an EAPI2 package or vice versa. Then you end up with a dozen
> potential ways of doing it, choose one randomly and hope that was a
> sane decision.
> 
> Having a consistent phase order is the only way to keep things
> predictable ...

The way that was chosen resulted in things being broken and a mad
scramble to fix things. There are at least two ways of doing it in an
entirely well defined manner that wouldn't have involved changing any
existing packages.

> > That's not how the system works. We're supposed to be documenting
> > what ebuilds may rely upon from compliant package managers. Since
> > there are compliant package managers that use both behaviours, the
> > documentation's supposed to reflect that.
> Hrm. All versions of all officially supported package managers I can
> see use the "newer" behaviour. So the "old" behaviour might be
> interesting for historical reasons, but anything currently in use is
> forced to rely on the "new" behaviour.

That's not how the system works. We don't pretend old behaviour never
existed.

> > > Feel free to document historic behaviour if you want, but as PMS
> > > hasn't documented it before I'd put it in the errata section. 
> > Doesn't PMS currently document the old way of doing it, not the new
> > way?
> See, that's what happens when you don't document what is actually
> happening.

No, it's what happens when you document what happens and then someone
goes and changes things to directly violate the specification.

> Either way there's a lot that needs to be done until PMS deserves the
> S in its name, but it's not hopeless. At least we're noticing the
> things it doesn't document or doesn't document correctly quite nicely.

Please provide examples of standards that have been retroactively
modified after publication to deal with implementations changing
behaviour.

-- 
Ciaran McCreesh

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 198 bytes --]