[gentoo-pms] [PATCH] Explain eapply behavior for EAPI 6

[gentoo-pms] [PATCH] Explain eapply behavior for EAPI 6

[Michał Górny]

---
 pkg-mgr-commands.tex | 32 ++++++++++++++++++++++++++++----
 1 file changed, 28 insertions(+), 4 deletions(-)

// I'm aware this isn't perfect but I tried to keep the algorithm
// readable and reasonably concise. Hope it's good enough for a start
// though.

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index dbdbdfd..1d57d63 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -148,10 +148,12 @@ These commands are used during the \t{src\_prepare} phase to apply patches to th
 Ebuilds must not run any of these commands once the current phase function has returned.
 
 \begin{description}
-\item[eapply] \featurelabel{eapply}
-    Only available in EAPIs listed in table~\ref{tab:patch-commands} as supporting \t{eapply}.
+\item[eapply] \featurelabel{eapply} Takes zero or more patch(1) options, followed by one or more
+	file or directory paths. Processes options and applies all patches found in specified locations
+	according to Algorithm~\ref{alg:eapply}. Only available in EAPIs listed in
+	table~\ref{tab:patch-commands} as supporting \t{eapply}.
 
-\item[eapply\_user] \featurelabel{eapply-user} Takes no arguments. Package managers supporting it
+\item[eapply\_user] \featurelabel{eapply-user} Takes no arguments. Package managers supporting i
     apply user-provided patches to the source tree in the current working directory. Exact behaviour
     is implementation defined and beyond the scope of this specification. Package managers not
     supporting it must implement the function as a no-op. Only available in EAPIs listed in
@@ -161,7 +163,29 @@ Ebuilds must not run any of these commands once the current phase function has r
 \begin{algorithm}
 \caption{eapply logic} \label{alg:eapply}
 \begin{algorithmic}[1]
-\STATE \COMMENT{WORK IN PROGRESS}
+\STATE let options=()
+\STATE let infiles=FALSE
+\FOR{\$x in parameters}
+	\IF{infiles is FALSE}
+		\IF{\$x is "\t{-{}-}"}
+			\STATE let infiles=TRUE
+		\ELSIF{\$x starts with "\t{-}"}
+			\STATE options+=( "\$x" )
+		\ELSE
+			\STATE let infiles=TRUE
+		\ENDIF
+	\ENDIF
+
+	\IF{infiles is TRUE}
+		\IF{\$x is a directory}
+			\FOR{\$f in all files matching \$x/*.diff and \$x/*.patch}
+				\STATE call \t{patch -p1 -f -s "\$\{options[@]\}" "\$f"}
+			\ENDFOR
+		\ELSE
+			\STATE call \t{patch -p1 -f -s "\$\{options[@]\}" "\$x"}
+		\ENDIF
+	\ENDIF
+\ENDFOR
 \end{algorithmic}
 \end{algorithm}
 
-- 
2.6.1

[gentoo-pms] Re: [PATCH] Explain eapply behavior for EAPI 6

[Ulrich Mueller]

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

>>>>> On Wed, 14 Oct 2015, Michał Górny wrote:

> ---
>  pkg-mgr-commands.tex | 32 ++++++++++++++++++++++++++++----
>  1 file changed, 28 insertions(+), 4 deletions(-)

> // I'm aware this isn't perfect but I tried to keep the algorithm
> // readable and reasonably concise. Hope it's good enough for a start
> // though.

Thanks, this will indeed serve well as a start.

> diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
> index dbdbdfd..1d57d63 100644
> --- a/pkg-mgr-commands.tex
> +++ b/pkg-mgr-commands.tex
> @@ -148,10 +148,12 @@ These commands are used during the \t{src\_prepare} phase to apply patches to th
>  Ebuilds must not run any of these commands once the current phase function has returned.
>   
>  \begin{description}
> -\item[eapply] \featurelabel{eapply}
> -    Only available in EAPIs listed in table~\ref{tab:patch-commands} as supporting \t{eapply}.
> +\item[eapply] \featurelabel{eapply} Takes zero or more patch(1) options, followed by one or more

Should we say "GNU patch" here? We require it in ebuild-env-commands.tex.

> +	file or directory paths. Processes options and applies all patches found in specified locations
> +	according to Algorithm~\ref{alg:eapply}. Only available in EAPIs listed in
> +	table~\ref{tab:patch-commands} as supporting \t{eapply}.
>  

> -\item[eapply\_user] \featurelabel{eapply-user} Takes no arguments. Package managers supporting it
> +\item[eapply\_user] \featurelabel{eapply-user} Takes no arguments. Package managers supporting i

Slip of fingers.

>      apply user-provided patches to the source tree in the current working directory. Exact behaviour
>      is implementation defined and beyond the scope of this specification. Package managers not
>      supporting it must implement the function as a no-op. Only available in EAPIs listed in
> @@ -161,7 +163,29 @@ Ebuilds must not run any of these commands once the current phase function has r
>  \begin{algorithm}
>  \caption{eapply logic} \label{alg:eapply}
>  \begin{algorithmic}[1]
> -\STATE \COMMENT{WORK IN PROGRESS}
> +\STATE let options=()
> +\STATE let infiles=FALSE
> +\FOR{\$x in parameters}
> +	\IF{infiles is FALSE}
> +		\IF{\$x is "\t{-{}-}"}
> +			\STATE let infiles=TRUE
> +		\ELSIF{\$x starts with "\t{-}"}
> +			\STATE options+=( "\$x" )
> +		\ELSE
> +			\STATE let infiles=TRUE
> +		\ENDIF
> +	\ENDIF
> +
> +	\IF{infiles is TRUE}

I wonder if it wouldn't be cleaner to do the whole option parsing
first. Something along the lines of this:

    IF first parameter begins with a hyphen AND any parameter is equal to --
        collect all parameters before the first -- in the options array
        collect all parameters after the first -- in the files array
    ELSIF any parameter beginning with a hyphen follows one without a hyphen
        return an error
    ELSE
        collect all parameters starting with a hyphen in the options array
        collect all parameters without a hyphen in the files array
    ENDIF

    FOR x in files
        ...

> +		\IF{\$x is a directory}
> +			\FOR{\$f in all files matching \$x/*.diff and \$x/*.patch}
> +				\STATE call \t{patch -p1 -f -s "\$\{options[@]\}" "\$f"}

Options "-p1 -g0 -E --no-backup-if-mismatch" are field-proven in
eutils.eclass. This doesn't mean that we have to adhere to it
slavishly, but I would suggest that we keep both the -g0 and the
--no-backup-if-mismatch options (but drop -E). Also I would omit
the -s; it is up to the PM if it wants to suppress or filter output.
So in summary, that is:

patch -p1 -f -g0 --no-backup-if-mismatch

> +			\ENDFOR
> +		\ELSE
> +			\STATE call \t{patch -p1 -f -s "\$\{options[@]\}" "\$x"}
> +		\ENDIF
> +	\ENDIF
> +\ENDFOR
>  \end{algorithmic}
>  \end{algorithm}

We should say something about error handling. For example, does the
function return when it encounters the first error of a called
patch(1)?

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: [gentoo-pms] Re: [PATCH] Explain eapply behavior for EAPI 6

[Michał Górny]

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

Dnia 2015-10-14, o godz. 20:24:22
Ulrich Mueller <ulm@gentoo.org> napisał(a):

> >>>>> On Wed, 14 Oct 2015, Michał Górny wrote:
> 
> > ---
> >  pkg-mgr-commands.tex | 32 ++++++++++++++++++++++++++++----
> >  1 file changed, 28 insertions(+), 4 deletions(-)
> 
> > // I'm aware this isn't perfect but I tried to keep the algorithm
> > // readable and reasonably concise. Hope it's good enough for a start
> > // though.
> 
> Thanks, this will indeed serve well as a start.
> 
> > diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
> > index dbdbdfd..1d57d63 100644
> > --- a/pkg-mgr-commands.tex
> > +++ b/pkg-mgr-commands.tex
> > @@ -148,10 +148,12 @@ These commands are used during the \t{src\_prepare} phase to apply patches to th
> >  Ebuilds must not run any of these commands once the current phase function has returned.
> >   
> >  \begin{description}
> > -\item[eapply] \featurelabel{eapply}
> > -    Only available in EAPIs listed in table~\ref{tab:patch-commands} as supporting \t{eapply}.
> > +\item[eapply] \featurelabel{eapply} Takes zero or more patch(1) options, followed by one or more
> 
> Should we say "GNU patch" here? We require it in ebuild-env-commands.tex.

Sure, updated.

> > +	file or directory paths. Processes options and applies all patches found in specified locations
> > +	according to Algorithm~\ref{alg:eapply}. Only available in EAPIs listed in
> > +	table~\ref{tab:patch-commands} as supporting \t{eapply}.
> >  
> 
> > -\item[eapply\_user] \featurelabel{eapply-user} Takes no arguments. Package managers supporting it
> > +\item[eapply\_user] \featurelabel{eapply-user} Takes no arguments. Package managers supporting i
> 
> Slip of fingers.

Corrected.

> 
> >      apply user-provided patches to the source tree in the current working directory. Exact behaviour
> >      is implementation defined and beyond the scope of this specification. Package managers not
> >      supporting it must implement the function as a no-op. Only available in EAPIs listed in
> > @@ -161,7 +163,29 @@ Ebuilds must not run any of these commands once the current phase function has r
> >  \begin{algorithm}
> >  \caption{eapply logic} \label{alg:eapply}
> >  \begin{algorithmic}[1]
> > -\STATE \COMMENT{WORK IN PROGRESS}
> > +\STATE let options=()
> > +\STATE let infiles=FALSE
> > +\FOR{\$x in parameters}
> > +	\IF{infiles is FALSE}
> > +		\IF{\$x is "\t{-{}-}"}
> > +			\STATE let infiles=TRUE
> > +		\ELSIF{\$x starts with "\t{-}"}
> > +			\STATE options+=( "\$x" )
> > +		\ELSE
> > +			\STATE let infiles=TRUE
> > +		\ENDIF
> > +	\ENDIF
> > +
> > +	\IF{infiles is TRUE}
> 
> I wonder if it wouldn't be cleaner to do the whole option parsing
> first. Something along the lines of this:

Not sure about this. But maybe it makes sense if we can get the right
wording...

>     IF first parameter begins with a hyphen AND any parameter is equal to --

Hmm, that's not exactly correct. All parameters preceding -- would have
to begin with a hyphen. So maybe...

      IF any parameter is equal to -- AND all parameters preceding it
        being with a hyphen

>         collect all parameters before the first -- in the options array
>         collect all parameters after the first -- in the files array
>     ELSIF any parameter beginning with a hyphen follows one without a hyphen
>         return an error

Not sure if we should really specify error handling here. The idea is
that this is incorrect syntax, so it is unconditional fatal error.

>     ELSE
>         collect all parameters starting with a hyphen in the options array
>         collect all parameters without a hyphen in the files array
>     ENDIF
> 
>     FOR x in files
>         ...
> 
> > +		\IF{\$x is a directory}
> > +			\FOR{\$f in all files matching \$x/*.diff and \$x/*.patch}
> > +				\STATE call \t{patch -p1 -f -s "\$\{options[@]\}" "\$f"}
> 
> Options "-p1 -g0 -E --no-backup-if-mismatch" are field-proven in
> eutils.eclass. This doesn't mean that we have to adhere to it
> slavishly, but I would suggest that we keep both the -g0 and the
> --no-backup-if-mismatch options (but drop -E). Also I would omit
> the -s; it is up to the PM if it wants to suppress or filter output.
> So in summary, that is:
> 
> patch -p1 -f -g0 --no-backup-if-mismatch

Ok.

> 
> > +			\ENDFOR
> > +		\ELSE
> > +			\STATE call \t{patch -p1 -f -s "\$\{options[@]\}" "\$x"}
> > +		\ENDIF
> > +	\ENDIF
> > +\ENDFOR
> >  \end{algorithmic}
> >  \end{algorithm}
> 
> We should say something about error handling. For example, does the
> function return when it encounters the first error of a called
> patch(1)?

Where should I say it? Put in the algorithm?

-- 
Best regards,
Michał Górny
<http://dev.gentoo.org/~mgorny/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 949 bytes --]

Re: [gentoo-pms] Re: [PATCH] Explain eapply behavior for EAPI 6

[Ulrich Mueller]

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

>>>>> On Wed, 14 Oct 2015, Michał Górny wrote:

>> IF first parameter begins with a hyphen AND any parameter is equal to --

> Hmm, that's not exactly correct. All parameters preceding -- would have
> to begin with a hyphen. So maybe...

>       IF any parameter is equal to -- AND all parameters preceding it
>         being with a hyphen

Well, there could be option arguments, too. And we don't know which
patch options can have arguments, unless we copy the option parsing
from patch(1) which is not feasible.

My wording was like this on purpose, and the idea is that if the
ebuild author has specified an explicit -- separator, then we assume
the he knows what he is doing. So we pass the whole part before the --
as options (plus possibly option arguments) to patch.

>> collect all parameters before the first -- in the options array
>> collect all parameters after the first -- in the files array
>> ELSIF any parameter beginning with a hyphen follows one without a hyphen
>> return an error

> Not sure if we should really specify error handling here. The idea is
> that this is incorrect syntax, so it is unconditional fatal error.

Sure, s/return an error/abort the build process/

>> ELSE
>> collect all parameters starting with a hyphen in the options array
>> collect all parameters without a hyphen in the files array
>> ENDIF

>> patch -p1 -f -g0 --no-backup-if-mismatch

> Ok.

Good. :)

>> We should say something about error handling. For example, does the
>> function return when it encounters the first error of a called
>> patch(1)?

> Where should I say it? Put in the algorithm?

Not sure, error exits tend to be clumsy. Does the algorithmic package
include a GOTO statement? :) To be serious, maybe it's best to leave
it out of the algorithm for better clarity, and put it into the
description instead.

What about nonfatal, BTW? We should be consistent with other commands
there.

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: [gentoo-pms] Re: [PATCH] Explain eapply behavior for EAPI 6

[Michał Górny]

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

Dnia 2015-10-14, o godz. 20:52:30
Ulrich Mueller <ulm@gentoo.org> napisał(a):

> >>>>> On Wed, 14 Oct 2015, Michał Górny wrote:
> 
> >> IF first parameter begins with a hyphen AND any parameter is equal to --
> 
> > Hmm, that's not exactly correct. All parameters preceding -- would have
> > to begin with a hyphen. So maybe...
> 
> >       IF any parameter is equal to -- AND all parameters preceding it
> >         being with a hyphen
> 
> Well, there could be option arguments, too. And we don't know which
> patch options can have arguments, unless we copy the option parsing
> from patch(1) which is not feasible.
> 
> My wording was like this on purpose, and the idea is that if the
> ebuild author has specified an explicit -- separator, then we assume
> the he knows what he is doing. So we pass the whole part before the --
> as options (plus possibly option arguments) to patch.

Oh crap, I totally forgot about option arguments. Then yes, probably
using -- to allow them makes sense.

> >> collect all parameters before the first -- in the options array
> >> collect all parameters after the first -- in the files array
> >> ELSIF any parameter beginning with a hyphen follows one without a hyphen
> >> return an error
> 
> > Not sure if we should really specify error handling here. The idea is
> > that this is incorrect syntax, so it is unconditional fatal error.
> 
> Sure, s/return an error/abort the build process/

Ok.

> >> ELSE
> >> collect all parameters starting with a hyphen in the options array
> >> collect all parameters without a hyphen in the files array
> >> ENDIF
> 
> >> patch -p1 -f -g0 --no-backup-if-mismatch
> 
> > Ok.
> 
> Good. :)
> 
> >> We should say something about error handling. For example, does the
> >> function return when it encounters the first error of a called
> >> patch(1)?
> 
> > Where should I say it? Put in the algorithm?
> 
> Not sure, error exits tend to be clumsy. Does the algorithmic package
> include a GOTO statement? :) To be serious, maybe it's best to leave
> it out of the algorithm for better clarity, and put it into the
> description instead.

No, it doesn't have a GOTO. But I think I can just put a STATE telling
it to exit.

> What about nonfatal, BTW? We should be consistent with other commands
> there.

Yes, that's the design. Dies without it, exits on first error with it.

-- 
Best regards,
Michał Górny
<http://dev.gentoo.org/~mgorny/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 949 bytes --]

[gentoo-pms] [PATCH v2] Explain eapply behavior for EAPI 6

[Michał Górny]

---
 pkg-mgr-commands.tex | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index dbdbdfd..324295f 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -148,8 +148,11 @@ These commands are used during the \t{src\_prepare} phase to apply patches to th
 Ebuilds must not run any of these commands once the current phase function has returned.
 
 \begin{description}
-\item[eapply] \featurelabel{eapply}
-    Only available in EAPIs listed in table~\ref{tab:patch-commands} as supporting \t{eapply}.
+\item[eapply] \featurelabel{eapply} Takes zero or more GNU patch options, followed by one or more
+	file or directory paths. Processes options and applies all patches found in specified locations
+	according to Algorithm~\ref{alg:eapply}. If it fails, it aborts the build using \t{die},
+	unless run using \t{nonfatal}, in which case it returns non-zero exit status. Only available
+	in EAPIs listed in table~\ref{tab:patch-commands} as supporting \t{eapply}.
 
 \item[eapply\_user] \featurelabel{eapply-user} Takes no arguments. Package managers supporting it
     apply user-provided patches to the source tree in the current working directory. Exact behaviour
@@ -161,7 +164,31 @@ Ebuilds must not run any of these commands once the current phase function has r
 \begin{algorithm}
 \caption{eapply logic} \label{alg:eapply}
 \begin{algorithmic}[1]
-\STATE \COMMENT{WORK IN PROGRESS}
+\IF{any parameter is equal to \t{"-{}-"}}
+	\STATE collect all parameters before the first \t{"-{}-"} in the options array
+	\STATE collect all parameters after the first \t{"-{}-"} in the files array
+\ELSIF{any parameter beginning with a hyphen follows one that does not begin with a hyphen}
+	\STATE abort the build process with an error
+\ELSE
+	\STATE collect all parameters beginning with a hyphen in the options array
+	\STATE collect all remaining parameters in the files array
+\ENDIF
+
+\FOR{\$x in files}
+	\IF{\$x is a directory}
+		\FOR{\$f in all files matching \$x/*.diff and \$x/*.patch}
+			\STATE call \t{patch -p1 -f -g0 --no-backup-if-mismatch "\$\{options[@]\}" "\$f"}
+			\IF{spawned patch process returns with non-zero exit status}
+				\STATE return immediately with an error
+			\ENDIF
+		\ENDFOR
+	\ELSE
+		\STATE call \t{patch -p1 -f -g0 --no-backup-if-mismatch "\$\{options[@]\}" "\$x"}
+		\IF{spawned patch process returns with non-zero exit status}
+			\STATE return immediately with an error
+		\ENDIF
+	\ENDIF
+\ENDFOR
 \end{algorithmic}
 \end{algorithm}
 
-- 
2.6.1

[gentoo-pms] Re: [PATCH v2] Explain eapply behavior for EAPI 6

[Ulrich Mueller]

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

>>>>> On Wed, 14 Oct 2015, Michał Górny wrote:

> +\IF{any parameter is equal to \t{"-{}-"}}
> +	\STATE collect all parameters before the first \t{"-{}-"} in the options array
> +	\STATE collect all parameters after the first \t{"-{}-"} in the files array

Hm, I previously had "IF the first parameter begins with a hyphen AND
any parameter is equal to --", because the first parameter certainly
cannot be an option argument.

> +\ELSIF{any parameter beginning with a hyphen follows one that does not begin with a hyphen}
> +	\STATE abort the build process with an error

I suggest "return immediately with an error" here, for consistency
with the wording below.

> +			\IF{spawned patch process returns with non-zero exit status}

I think "child process" is better here.

> +				\STATE return immediately with an error
> +			\ENDIF

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: [gentoo-pms] Re: [PATCH v2] Explain eapply behavior for EAPI 6

[Michał Górny]

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

Dnia 2015-10-14, o godz. 21:40:03
Ulrich Mueller <ulm@gentoo.org> napisał(a):

> >>>>> On Wed, 14 Oct 2015, Michał Górny wrote:
> 
> > +\IF{any parameter is equal to \t{"-{}-"}}
> > +	\STATE collect all parameters before the first \t{"-{}-"} in the options array
> > +	\STATE collect all parameters after the first \t{"-{}-"} in the files array
> 
> Hm, I previously had "IF the first parameter begins with a hyphen AND
> any parameter is equal to --", because the first parameter certainly
> cannot be an option argument.

I know. But does it really make a difference in our case? I wanted to
try to make the algorithm a little simpler.

> 
> > +\ELSIF{any parameter beginning with a hyphen follows one that does not begin with a hyphen}
> > +	\STATE abort the build process with an error
> 
> I suggest "return immediately with an error" here, for consistency
> with the wording below.

Well, I wanted to emphasize difference in error handling. patch failing
implies error exit with respect to nonfatal. Usage error is
unconditional die.

> 
> > +			\IF{spawned patch process returns with non-zero exit status}
> 
> I think "child process" is better here.

Updated.

-- 
Best regards,
Michał Górny
<http://dev.gentoo.org/~mgorny/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 949 bytes --]

Re: [gentoo-pms] Re: [PATCH v2] Explain eapply behavior for EAPI 6

[Ulrich Mueller]

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

>>>>> On Wed, 14 Oct 2015, Michał Górny wrote:

>> Hm, I previously had "IF the first parameter begins with a hyphen
>> AND any parameter is equal to --", because the first parameter
>> certainly cannot be an option argument.

> I know. But does it really make a difference in our case? I wanted
> to try to make the algorithm a little simpler.

*shrug* Let GNU patch choke on it then.

>> > +\ELSIF{any parameter beginning with a hyphen follows one that does not begin with a hyphen}
>> > +	\STATE abort the build process with an error
>> 
>> I suggest "return immediately with an error" here, for consistency
>> with the wording below.

> Well, I wanted to emphasize difference in error handling. patch
> failing implies error exit with respect to nonfatal. Usage error is
> unconditional die.

I see, but then the wording might be more explicit. Maybe instead of
"If it fails" say "If applying the patches fails" in the description?

Ulrich

[-- Attachment #2: Type: application/pgp-signature, Size: 490 bytes --]

Re: [gentoo-pms] Re: [PATCH v2] Explain eapply behavior for EAPI 6

[Michał Górny]

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

Dnia 2015-10-14, o godz. 22:10:38
Ulrich Mueller <ulm@gentoo.org> napisał(a):

> >>>>> On Wed, 14 Oct 2015, Michał Górny wrote:
> 
> >> Hm, I previously had "IF the first parameter begins with a hyphen
> >> AND any parameter is equal to --", because the first parameter
> >> certainly cannot be an option argument.
> 
> > I know. But does it really make a difference in our case? I wanted
> > to try to make the algorithm a little simpler.
> 
> *shrug* Let GNU patch choke on it then.
> 
> >> > +\ELSIF{any parameter beginning with a hyphen follows one that does not begin with a hyphen}
> >> > +	\STATE abort the build process with an error
> >> 
> >> I suggest "return immediately with an error" here, for consistency
> >> with the wording below.
> 
> > Well, I wanted to emphasize difference in error handling. patch
> > failing implies error exit with respect to nonfatal. Usage error is
> > unconditional die.
> 
> I see, but then the wording might be more explicit. Maybe instead of
> "If it fails" say "If applying the patches fails" in the description?

Done. Let me resubmit once again.

-- 
Best regards,
Michał Górny
<http://dev.gentoo.org/~mgorny/>

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 949 bytes --]

[gentoo-pms] [PATCH v3] Explain eapply behavior for EAPI 6

[Michał Górny]

---
 pkg-mgr-commands.tex | 33 ++++++++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/pkg-mgr-commands.tex b/pkg-mgr-commands.tex
index dbdbdfd..891a437 100644
--- a/pkg-mgr-commands.tex
+++ b/pkg-mgr-commands.tex
@@ -148,8 +148,11 @@ These commands are used during the \t{src\_prepare} phase to apply patches to th
 Ebuilds must not run any of these commands once the current phase function has returned.
 
 \begin{description}
-\item[eapply] \featurelabel{eapply}
-    Only available in EAPIs listed in table~\ref{tab:patch-commands} as supporting \t{eapply}.
+\item[eapply] \featurelabel{eapply} Takes zero or more GNU patch options, followed by one or more
+	file or directory paths. Processes options and applies all patches found in specified locations
+	according to Algorithm~\ref{alg:eapply}. If applying the patches fails, it aborts the build
+	using \t{die}, unless run using \t{nonfatal}, in which case it returns non-zero exit status.
+	Only available in EAPIs listed in table~\ref{tab:patch-commands} as supporting \t{eapply}.
 
 \item[eapply\_user] \featurelabel{eapply-user} Takes no arguments. Package managers supporting it
     apply user-provided patches to the source tree in the current working directory. Exact behaviour
@@ -161,7 +164,31 @@ Ebuilds must not run any of these commands once the current phase function has r
 \begin{algorithm}
 \caption{eapply logic} \label{alg:eapply}
 \begin{algorithmic}[1]
-\STATE \COMMENT{WORK IN PROGRESS}
+\IF{any parameter is equal to \t{"-{}-"}}
+	\STATE collect all parameters before the first \t{"-{}-"} in the options array
+	\STATE collect all parameters after the first \t{"-{}-"} in the files array
+\ELSIF{any parameter beginning with a hyphen follows one that does not begin with a hyphen}
+	\STATE abort the build process with an error
+\ELSE
+	\STATE collect all parameters beginning with a hyphen in the options array
+	\STATE collect all remaining parameters in the files array
+\ENDIF
+
+\FOR{\$x in files}
+	\IF{\$x is a directory}
+		\FOR{\$f in all files matching \$x/*.diff and \$x/*.patch}
+			\STATE call \t{patch -p1 -f -g0 --no-backup-if-mismatch "\$\{options[@]\}" "\$f"}
+			\IF{child process returns with non-zero exit status}
+				\STATE return immediately with an error
+			\ENDIF
+		\ENDFOR
+	\ELSE
+		\STATE call \t{patch -p1 -f -g0 --no-backup-if-mismatch "\$\{options[@]\}" "\$x"}
+		\IF{child process returns with non-zero exit status}
+			\STATE return immediately with an error
+		\ENDIF
+	\ENDIF
+\ENDFOR
 \end{algorithmic}
 \end{algorithm}
 
-- 
2.6.1