Re: What should "guix build --source" produce? (was Re: Dependency cycle issues when using a Gexp-based snippet)

[Maxim Cournoyer <maxim.cournoyer@gmail.com>]

Andreas Enge <andreas@enge.fr> writes:

> Hello Mark,
>
> On Tue, Sep 08, 2020 at 12:07:01AM -0400, Mark H Weaver wrote:
>> > +                     (let ((coreutils #+(canonical-package coreutils)))
>> > +                       (substitute* "configure"
>> > +                         (("/bin/pwd")
>> > +                          (string-append coreutils "/bin/pwd")))
>> > +                       (substitute* "src/corelib/global/global.pri"
>> > +                         (("/bin/ls")
>> > +                          (string-append coreutils "/bin/ls"))))
>> > +                     #t)))))
>> 
>> In my opinion, "guix build --source PACKAGE" should produce sources that
>> can be used to build the package on any system that the upstream package
>> supports, not just on Guix systems.
>
> that sounds good to me, in particular taking your subsequent arguments into
> account. Guix sources could be just as useful as Debian sources in this
> respect. Could this not be the elusive boundary between preparing the source
> and adding a phase to the build arguments?

Yes, this sounds like it!  How about the following section, to help
contributors decide between the two?

--8<---------------cut here---------------start------------->8---
1 file changed, 14 insertions(+)
doc/contributing.texi | 14 ++++++++++++++

modified   doc/contributing.texi
@@ -369,6 +369,7 @@ needed is to review and apply the patch.
 * Package Naming::              What's in a name?
 * Version Numbers::             When the name is not enough.
 * Synopses and Descriptions::   Helping users find the right package.
+* Snippets versus Phases::      Whether to use a snippet, or a build phase.
 * Python Modules::              A touch of British comedy.
 * Perl Modules::                Little pearls.
 * Java Packages::               Coffee break.
@@ -599,6 +600,19 @@ Gettext}):
 for the X11 resize-and-rotate (RandR) extension. @dots{}")
 @end example
 
+@node Snippets versus phases
+@subsection Snippets versus phases
+
+@cindex snippets, when to use
+The boundary between using an origin snippet versus a build phase to
+modify the sources of a package can be elusive.  Origin snippets are
+typically used to remove unnecessary files such as bundled libraries,
+nonfree sources, or to apply simple substitutions.  The source derived
+from an origin should produce a source that can be used to build the
+package on any system that the upstream package supports (i.e., act as
+the corresponding source).  In particular, origin patches or snippets
+must not embed store items in the sources; such patching should rather
+be done using build phases.
 
 @node Python Modules
 @subsection Python Modules
--8<---------------cut here---------------end--------------->8---

Thanks,

Maxim