myglc2 <myglc2@gmail.com> writes:

> On 11/10/2017 at 15:30 Chris Marusich writes:
>
>> Hi Leo,
>>
>> Leo Famulari <leo@famulari.name> writes:
>>
>>> Substition is considered to fail when Guix is expecting a substitute but
>>> the server returns 404, 504, or some other unexpected problem occurs. It
>>> is not considered to fail if the server initially reports that no
>>> substitute is available.
>
> Hi Leo, this is a wonderful clarification of behavior that has confused
> me for 1.5 years!
>>
>> Thank you for the clarification.  This is what I did not understand.  I
>> read the manual and got the impression that when --fallback has not been
>> given, if a given substitute cannot be found (regardless of whether or
>> not a substitute server claimed to provide one), then Guix will not
>> build it.  I see now that my understanding was mistaken.
>
> I had this mistaken impression too.
>>
>> I've attached a patch which tries to clarify this in the manual.  What
>> do you think of it?
>
> Hey Chris,
>
> How about saying what Leo said right up front in the substitutes
> section. This allows the --fallback addition to be more brief.
>
> Rough draft below.
>
> WDYT? - George
>
> 1 file changed, 9 insertions(+), 2 deletions(-)
> doc/guix.texi | 11 +++++++++--
>
> modified   doc/guix.texi
> @@ -2120,6 +2120,13 @@ server.  We call these pre-built items @dfn{substitutes}---they are
>  substitutes for local build results.  In many cases, downloading a
>  substitute is much faster than building things locally.
>  
> +When substitutes are enabled (the default) and a substitute is not
> +available the build will take place locally. If a substitute is
> +available but substitution fails, e.g., the substitute server returns
> +404, 504, times out, or some other unexpected problem occurs, guix stops
> +and reports an error unless --fallback or --keep-going options are
> +specified.
> +
>  Substitutes can be anything resulting from a derivation build
>  (@pxref{Derivations}).  Of course, in the common case, they are
>  pre-built package binaries, but source tarballs, for instance, which
> @@ -5192,8 +5199,8 @@ derivations has failed.
>  Do not build the derivations.
>  
>  @item --fallback
> -When substituting a pre-built binary fails, fall back to building
> -packages locally.
> +Attempt to build locally instead of issuing an error when substitutes
> +are enabled and the substitution of a pre-built binary fails.
>  
>  @item --substitute-urls=@var{urls}
>  @anchor{client-substitute-urls}

I think I like the way you wrote it better.  I'm fine with that.  I was
hoping not to add to the already-voluminous paragraphs about Substitutes
at the top of section 3.3, but honestly as long as this info is in the
manual, I'm happy.

-- 
Chris