[PATCH] doc: rephrase code of conduct.

[PATCH] doc: rephrase code of conduct.

[Alex Sassmannshausen]

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

Hello,

Below you *should* find the patch for the new phrasing of the code of
conduct section in the manual.

Let me know if anything seems amiss.

Cheers,

Alex


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Code of Conduct patch --]
[-- Type: text/x-patch, Size: 1525 bytes --]

From 76576c88d81233095d61ec97308521c7d29fa94e Mon Sep 17 00:00:00 2001
From: Alex Sassmannshausen <alex.sassmannshausen@gmail.com>
Date: Wed, 9 Dec 2015 18:12:09 +0100
Subject: [PATCH] doc: rephrase 'code of conduct' section.

* doc/contributing.texi (Contributing): Rephrase 'code of conduct'
  section.
---
 doc/contributing.texi | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/doc/contributing.texi b/doc/contributing.texi
index b3a9365..54fb23a 100644
--- a/doc/contributing.texi
+++ b/doc/contributing.texi
@@ -9,12 +9,11 @@ particularly welcome help on packaging (@pxref{Packaging Guidelines}).
 
 @cindex code of conduct, of contributors
 @cindex contributor covenant
-In the interest of welcoming everyone who thinks this is a great project
-to contribute to---which it is, indeed!---contributors express their
-commitment to providing a warm, friendly, and harassment-free experience
-by agreeing to our ``Contributor Covenant'', adapted from
-@url{http://contributor-covenant.org/}, and which can be found in the
-@file{CODE-OF-CONDUCT} file in the source tree.
+We want to provide a warm, friendly, and harassment-free environment, so
+that anyone can contribute to the best of their abilities.  To this end
+our project uses a ``Contributor Covenant'', which was adapted from
+@url{http://contributor-covenant.org/}.  You can find a local version in
+the @file{CODE-OF-CONDUCT} file in the source tree.
 
 @menu
 * Building from Git::           The latest and greatest.
-- 
2.6.3

package dependencies

[Fabian Harfert]

Hello,

at the moment I am making my first steps in packaging for guix. I would
like to know, how to define the dependences for a package correctly.

I see three fields in the documentation: "inputs", "native-inputs" and
"propagated" inputs. Am I right if I say that "native-inputs" stands
for build dependences and "inputs" is for runtime dependences?

In general I find the guix documentation very clear and useful - and
I have to say: guix is the best package manager I have met until now.

Fabian

Re: [PATCH] doc: rephrase code of conduct.

[Ludovic Courtès]

Pushed, thanks!

Ludo’.

Re: package dependencies

[Pjotr Prins]

Hi Fabian,

It has been noted before that these are not well explained in the docs. I like this 
description:

1. *native-inputs*: required for building but not runtime - installing a
   package through a substitute won't install these inputs
2. *inputs*: installed in the store but not in the profile, as well as being
   present at build time
3. *propagated-inputs*: installed in the store and in the profile, as
   well as being present at build time

(I proposed to update the docs at some point, in fact, but I realise
that some people may like the existing description better. Guile/Guix
are documented in a pretty consistent way).

You may also find information on https://github.com/pjotrp/guix-notes/
to be useful. That is basically where I jot down stuff I otherwise
would forget.

Pj.

On Wed, Dec 09, 2015 at 08:13:29PM +0100, Fabian Harfert wrote:
> Hello,
> 
> at the moment I am making my first steps in packaging for guix. I would
> like to know, how to define the dependences for a package correctly.
> 
> I see three fields in the documentation: "inputs", "native-inputs" and
> "propagated" inputs. Am I right if I say that "native-inputs" stands
> for build dependences and "inputs" is for runtime dependences?
> 
> In general I find the guix documentation very clear and useful - and
> I have to say: guix is the best package manager I have met until now.
> 
> Fabian
> 

-- 

Re: package dependencies

[Ludovic Courtès]

Hello!

I’ve rephrased the doc in “package Reference” in a way that is hopefully
clearer:

     ‘inputs’ (default: ‘'()’)
     ‘native-inputs’ (default: ‘'()’)
     ‘propagated-inputs’ (default: ‘'()’)
          These fields list dependencies of the package.  Each one is a
          list of tuples, where each tuple has a label for the input (a
          string) as its first element, a package, origin, or derivation
          as its second element, and optionally the name of the output
          thereof that should be used, which defaults to ‘"out"’ (*note
          Packages with Multiple Outputs::, for more on package
          outputs).  For example, the list below specifies 3 inputs:

               `(("libffi" ,libffi)
                 ("libunistring" ,libunistring)
                 ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib

          The distinction between ‘native-inputs’ and ‘inputs’ is
          necessary when considering cross-compilation.  When
          cross-compiling, dependencies listed in ‘inputs’ are built for
          the _target_ architecture; conversely, dependencies listed in
          ‘native-inputs’ are built for the architecture of the _build_
          machine.

          ‘native-inputs’ is typically where you would list tools needed
          at build time but not at run time, such as Autoconf, Automake,
          pkg-config, Gettext, or Bison.  ‘guix lint’ can report likely
          mistakes in this area (*note Invoking guix lint::).

          Lastly, ‘propagated-inputs’ is similar to ‘inputs’, but the
          specified packages will be force-installed alongside the
          package they belong to (*note ‘guix package’:
          package-cmd-propagated-inputs, for information on how ‘guix
          package’ deals with propagated inputs.)

          For example this is necessary when a library needs headers of
          another library to compile, or needs another shared library to
          be linked alongside itself when a program wants to link to it.

HTH!

Ludo’.

Re: package dependencies

[Pjotr Prins]

Thanks Ludo. I still think it could be made a little clearer from the packager's 
perspective. How about concluding it with something like:

In short, to create a package, by default you should use 'inputs' for
dependencies. Use 'native-inputs' for tools used at build-time, but
not at runtime and use propagated-inputs when the other two do not
suffice.

On Sun, Dec 13, 2015 at 02:45:46PM +0100, Ludovic Courtès wrote:
> Hello!
> 
> I’ve rephrased the doc in “package Reference” in a way that is hopefully
> clearer:
> 
>      ‘inputs’ (default: ‘'()’)
>      ‘native-inputs’ (default: ‘'()’)
>      ‘propagated-inputs’ (default: ‘'()’)
>           These fields list dependencies of the package.  Each one is a
>           list of tuples, where each tuple has a label for the input (a
>           string) as its first element, a package, origin, or derivation
>           as its second element, and optionally the name of the output
>           thereof that should be used, which defaults to ‘"out"’ (*note
>           Packages with Multiple Outputs::, for more on package
>           outputs).  For example, the list below specifies 3 inputs:
> 
>                `(("libffi" ,libffi)
>                  ("libunistring" ,libunistring)
>                  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib
> 
>           The distinction between ‘native-inputs’ and ‘inputs’ is
>           necessary when considering cross-compilation.  When
>           cross-compiling, dependencies listed in ‘inputs’ are built for
>           the _target_ architecture; conversely, dependencies listed in
>           ‘native-inputs’ are built for the architecture of the _build_
>           machine.
> 
>           ‘native-inputs’ is typically where you would list tools needed
>           at build time but not at run time, such as Autoconf, Automake,
>           pkg-config, Gettext, or Bison.  ‘guix lint’ can report likely
>           mistakes in this area (*note Invoking guix lint::).
> 
>           Lastly, ‘propagated-inputs’ is similar to ‘inputs’, but the
>           specified packages will be force-installed alongside the
>           package they belong to (*note ‘guix package’:
>           package-cmd-propagated-inputs, for information on how ‘guix
>           package’ deals with propagated inputs.)
> 
>           For example this is necessary when a library needs headers of
>           another library to compile, or needs another shared library to
>           be linked alongside itself when a program wants to link to it.
> 
> HTH!
> 
> Ludo’.
> 

-- 

Re: package dependencies

[Leo Famulari]

On Sun, Dec 13, 2015 at 02:45:46PM +0100, Ludovic Courtès wrote:
> Hello!
> 
> I’ve rephrased the doc in “package Reference” in a way that is hopefully
> clearer:
> 
>      ‘inputs’ (default: ‘'()’)
>      ‘native-inputs’ (default: ‘'()’)
>      ‘propagated-inputs’ (default: ‘'()’)
>           These fields list dependencies of the package.  Each one is a
>           list of tuples, where each tuple has a label for the input (a
>           string) as its first element, a package, origin, or derivation
>           as its second element, and optionally the name of the output
>           thereof that should be used, which defaults to ‘"out"’ (*note
>           Packages with Multiple Outputs::, for more on package
>           outputs).  For example, the list below specifies 3 inputs:
> 
>                `(("libffi" ,libffi)
>                  ("libunistring" ,libunistring)
>                  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib
> 
>           The distinction between ‘native-inputs’ and ‘inputs’ is
>           necessary when considering cross-compilation.  When
>           cross-compiling, dependencies listed in ‘inputs’ are built for
>           the _target_ architecture; conversely, dependencies listed in
>           ‘native-inputs’ are built for the architecture of the _build_
>           machine.
> 
>           ‘native-inputs’ is typically where you would list tools needed
>           at build time but not at run time, such as Autoconf, Automake,
>           pkg-config, Gettext, or Bison.  ‘guix lint’ can report likely
>           mistakes in this area (*note Invoking guix lint::).
> 
>           Lastly, ‘propagated-inputs’ is similar to ‘inputs’, but the
>           specified packages will be force-installed alongside the
>           package they belong to (*note ‘guix package’:
>           package-cmd-propagated-inputs, for information on how ‘guix
>           package’ deals with propagated inputs.)
> 
>           For example this is necessary when a library needs headers of
>           another library to compile, or needs another shared library to
>           be linked alongside itself when a program wants to link to it.

I think it's a good improvement! This is a big obstacle for new
packagers.

It may be worth linking between the sections about propagated-inputs and
the python-build-system, since the situation is somewhat different
there. At least in a footnote.

> 
> HTH!
> 
> Ludo’.
> 

Re: package dependencies

[Ben Woodcroft]

On 14/12/15 17:03, Leo Famulari wrote:
> On Sun, Dec 13, 2015 at 02:45:46PM +0100, Ludovic Courtès wrote:
>> Hello!
>>
>> I’ve rephrased the doc in “package Reference” in a way that is hopefully
>> clearer:
>>
>>       ‘inputs’ (default: ‘'()’)
>>       ‘native-inputs’ (default: ‘'()’)
>>       ‘propagated-inputs’ (default: ‘'()’)
>>            These fields list dependencies of the package.  Each one is a
>>            list of tuples, where each tuple has a label for the input (a
>>            string) as its first element, a package, origin, or derivation
>>            as its second element, and optionally the name of the output
>>            thereof that should be used, which defaults to ‘"out"’ (*note
>>            Packages with Multiple Outputs::, for more on package
>>            outputs).  For example, the list below specifies 3 inputs:
>>
>>                 `(("libffi" ,libffi)
>>                   ("libunistring" ,libunistring)
>>                   ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib
>>
>>            The distinction between ‘native-inputs’ and ‘inputs’ is
>>            necessary when considering cross-compilation.  When
>>            cross-compiling, dependencies listed in ‘inputs’ are built for
>>            the _target_ architecture; conversely, dependencies listed in
>>            ‘native-inputs’ are built for the architecture of the _build_
>>            machine.
>>
>>            ‘native-inputs’ is typically where you would list tools needed
>>            at build time but not at run time, such as Autoconf, Automake,
>>            pkg-config, Gettext, or Bison.  ‘guix lint’ can report likely
>>            mistakes in this area (*note Invoking guix lint::).
>>
>>            Lastly, ‘propagated-inputs’ is similar to ‘inputs’, but the
>>            specified packages will be force-installed alongside the
>>            package they belong to (*note ‘guix package’:
>>            package-cmd-propagated-inputs, for information on how ‘guix
>>            package’ deals with propagated inputs.)
>>
>>            For example this is necessary when a library needs headers of
>>            another library to compile, or needs another shared library to
>>            be linked alongside itself when a program wants to link to it.
> I think it's a good improvement! This is a big obstacle for new
> packagers.
>
> It may be worth linking between the sections about propagated-inputs and
> the python-build-system, since the situation is somewhat different
> there. At least in a footnote.
+1. And perhaps making reference to scripting languages in general too.

Re: package dependencies

[Ludovic Courtès]

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

Leo Famulari <leo@famulari.name> skribis:

> On Sun, Dec 13, 2015 at 02:45:46PM +0100, Ludovic Courtès wrote:
>> Hello!
>> 
>> I’ve rephrased the doc in “package Reference” in a way that is hopefully
>> clearer:
>> 
>>      ‘inputs’ (default: ‘'()’)
>>      ‘native-inputs’ (default: ‘'()’)
>>      ‘propagated-inputs’ (default: ‘'()’)
>>           These fields list dependencies of the package.  Each one is a
>>           list of tuples, where each tuple has a label for the input (a
>>           string) as its first element, a package, origin, or derivation
>>           as its second element, and optionally the name of the output
>>           thereof that should be used, which defaults to ‘"out"’ (*note
>>           Packages with Multiple Outputs::, for more on package
>>           outputs).  For example, the list below specifies 3 inputs:
>> 
>>                `(("libffi" ,libffi)
>>                  ("libunistring" ,libunistring)
>>                  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib
>> 
>>           The distinction between ‘native-inputs’ and ‘inputs’ is
>>           necessary when considering cross-compilation.  When
>>           cross-compiling, dependencies listed in ‘inputs’ are built for
>>           the _target_ architecture; conversely, dependencies listed in
>>           ‘native-inputs’ are built for the architecture of the _build_
>>           machine.
>> 
>>           ‘native-inputs’ is typically where you would list tools needed
>>           at build time but not at run time, such as Autoconf, Automake,
>>           pkg-config, Gettext, or Bison.  ‘guix lint’ can report likely
>>           mistakes in this area (*note Invoking guix lint::).
>> 
>>           Lastly, ‘propagated-inputs’ is similar to ‘inputs’, but the
>>           specified packages will be force-installed alongside the
>>           package they belong to (*note ‘guix package’:
>>           package-cmd-propagated-inputs, for information on how ‘guix
>>           package’ deals with propagated inputs.)
>> 
>>           For example this is necessary when a library needs headers of
>>           another library to compile, or needs another shared library to
>>           be linked alongside itself when a program wants to link to it.
>
> I think it's a good improvement! This is a big obstacle for new
> packagers.
>
> It may be worth linking between the sections about propagated-inputs and
> the python-build-system, since the situation is somewhat different
> there. At least in a footnote.

Good point.  How about the patch below?  I’m not sure whether/how to
cross-reference from ‘python-build-system’ & co. since they don’t
mention the problem.

Thanks,
Ludo’.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Type: text/x-patch, Size: 1207 bytes --]

diff --git a/doc/guix.texi b/doc/guix.texi
index 29cea5c..7b7e118 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -2305,9 +2305,16 @@ belong to (@pxref{package-cmd-propagated-inputs, @command{guix
 package}}, for information on how @command{guix package} deals with
 propagated inputs.)
 
-For example this is necessary when a library needs headers of another
-library to compile, or needs another shared library to be linked
-alongside itself when a program wants to link to it.
+For example this is necessary when a C/C++ library needs headers of
+another library to compile, or when a pkg-config file refers to another
+one @i{via} its @code{Requires} field.
+
+Another example where @code{propagated-inputs} is useful is for
+languages that lack a facility to record the run-time search path akin
+to ELF's @code{RUNPATH}; this includes Guile, Python, Perl, GHC, and
+more.  To ensure that libraries written in those languages can find
+library code they depend on at run time, run-time dependencies must be
+listed in @code{propagated-inputs} rather than @code{inputs}.
 
 @item @code{self-native-input?} (default: @code{#f})
 This is a Boolean field telling whether the package should use itself as

Re: package dependencies

[Ludovic Courtès]

Pjotr Prins <pjotr.public12@thebird.nl> skribis:

> Thanks Ludo. I still think it could be made a little clearer from the packager's 
> perspective. How about concluding it with something like:
>
> In short, to create a package, by default you should use 'inputs' for
> dependencies. Use 'native-inputs' for tools used at build-time, but
> not at runtime and use propagated-inputs when the other two do not
> suffice.

This is certainly shorter, but the problem I have with that is that it
does not accurately explain what’s going on.  The current text is
admittedly more verbose, but I think it is more accurate.

Hope that makes sense.

Ludo’.

Re: package dependencies

[Pjotr Prins]

The problem with the main text is that it is written from the view
point of technology. I would like something more human that reads like
an instruction for packagers. Be great if we had something useful
there, otherwise questions will be asked again and again :). And I
will have to point to guix-notes every time.

I agree my version is less accurate, but it acts like a summing up and
(actually) is precisely the way I look at these statements. We can
have both. I am not saying we should replace your section.

Anyway, maybe I am the only one seeing it like this.

Pj.

On Mon, Dec 14, 2015 at 09:58:19AM +0100, Ludovic Courtès wrote:
> Pjotr Prins <pjotr.public12@thebird.nl> skribis:
> 
> > Thanks Ludo. I still think it could be made a little clearer from the packager's 
> > perspective. How about concluding it with something like:
> >
> > In short, to create a package, by default you should use 'inputs' for
> > dependencies. Use 'native-inputs' for tools used at build-time, but
> > not at runtime and use propagated-inputs when the other two do not
> > suffice.
> 
> This is certainly shorter, but the problem I have with that is that it
> does not accurately explain what’s going on.  The current text is
> admittedly more verbose, but I think it is more accurate.
> 
> Hope that makes sense.
> 
> Ludo’.
> 

-- 

Re: package dependencies

[Ludovic Courtès]

Pjotr Prins <pjotr.public12@thebird.nl> skribis:

> The problem with the main text is that it is written from the view
> point of technology. I would like something more human that reads like
> an instruction for packagers. Be great if we had something useful
> there, otherwise questions will be asked again and again :). And I
> will have to point to guix-notes every time.
>
> I agree my version is less accurate, but it acts like a summing up and
> (actually) is precisely the way I look at these statements. We can
> have both. I am not saying we should replace your section.
>
> Anyway, maybe I am the only one seeing it like this.

Maybe not!  I’m definitely biased, but I haven’t seen or thought of a
way to describe things more concisely without sacrificing accuracy.

Or maybe under “Defining Packages” we could give some sort of simpler
“rule of thumb” and point readers to the reference for details?  Would
that work?

Patches welcome!  :-)

Ludo’.

Re: package dependencies

[Leo Famulari]

On Mon, Dec 14, 2015 at 10:28:57AM +0100, Pjotr Prins wrote:
> The problem with the main text is that it is written from the view
> point of technology. I would like something more human that reads like
> an instruction for packagers. Be great if we had something useful
> there, otherwise questions will be asked again and again :). And I
> will have to point to guix-notes every time.

It's true, an extremely technical explanation will be completely useful
and accurate and ... it won't help many of the readers who actually need
help. It is very easy to package simple programs for Guix. But I have
found that as soon as the program deviates from the Autotools or
setup.py script at all, you really need some domain-specific technical
knowledge to finish the package. I have personally learned a lot about
many subjects while packaging for Guix.

See the recent ML thread about packaging 'sent'.

> 
> I agree my version is less accurate, but it acts like a summing up and
> (actually) is precisely the way I look at these statements. We can
> have both. I am not saying we should replace your section.

I think we are all loath to include inaccuracies in the manual. But on
the other hand, I think we need to find a way to summarize the
distinction that is close to what Pjotr is proposing.

Some of us have an understanding of the subject that is directly based
on the Guix / Nix source code. The rest of us have learned by
trial-and-error and rough heuristics like Pjotr's summary (hopefully we
will all 'use the source' eventually ;) .

The difficult thing is explaining it in a way that "sets up" the reader
for further learning. You must be accurate, but you must not be too
verbose, because when you are banging your head against the wall, it is
difficult to read a long text.

The other day, this helpful jewel was shared by mark_weaver on #guix [0]:
fhmgufs: the distinction between build and runtime dependencies is
determined by scanning the outputs of the build for references to
/gnu/store/....

Learning the mechanism made it clear to me. This is why Python inputs
must be propagated: there is nowhere in the main Python program to link
to dependencies in the store, so the inputs must be propagated onto
PYTHONPATH. I already understood the difference between 'native-inputs'
and 'inputs', and this doesn't really get to the heart of the
difference, but it does draw a line between them.

I propose we adapt this statement for use in the manual (assuming that
is accurate).

If there is no updated patch in a few hours, I will write one, but I
can't do it at the moment.

[0]
https://gnunet.org/bot/log/guix/2015-12-09

PS— I can't follow the "flow" of this conversation because some people
are replying in-line while others are top-posting. Please, let's pick
one (I vote for in-line).

> 
> Anyway, maybe I am the only one seeing it like this.
> 
> Pj.
> 
> On Mon, Dec 14, 2015 at 09:58:19AM +0100, Ludovic Courtès wrote:
> > Pjotr Prins <pjotr.public12@thebird.nl> skribis:
> > 
> > > Thanks Ludo. I still think it could be made a little clearer from the packager's 
> > > perspective. How about concluding it with something like:
> > >
> > > In short, to create a package, by default you should use 'inputs' for
> > > dependencies. Use 'native-inputs' for tools used at build-time, but
> > > not at runtime and use propagated-inputs when the other two do not
> > > suffice.
> > 
> > This is certainly shorter, but the problem I have with that is that it
> > does not accurately explain what’s going on.  The current text is
> > admittedly more verbose, but I think it is more accurate.
> > 
> > Hope that makes sense.
> > 
> > Ludo’.
> > 
> 
> -- 
> 

Re: package dependencies

[Pjotr Prins]

Another way to go about this is to create a manual for packagers. My
guix-notes is more general (mostly to help my memory), and then there
is the wiki-thing. But I agree we don't have a very helpful starting
point for packagers considering they need to learn multiple things at
the same time (not least Guile ;).

Pj.

On Mon, Dec 14, 2015 at 02:36:54PM -0500, Leo Famulari wrote:
> On Mon, Dec 14, 2015 at 10:28:57AM +0100, Pjotr Prins wrote:
> > The problem with the main text is that it is written from the view
> > point of technology. I would like something more human that reads like
> > an instruction for packagers. Be great if we had something useful
> > there, otherwise questions will be asked again and again :). And I
> > will have to point to guix-notes every time.
> 
> It's true, an extremely technical explanation will be completely useful
> and accurate and ... it won't help many of the readers who actually need
> help. It is very easy to package simple programs for Guix. But I have
> found that as soon as the program deviates from the Autotools or
> setup.py script at all, you really need some domain-specific technical
> knowledge to finish the package. I have personally learned a lot about
> many subjects while packaging for Guix.
> 
> See the recent ML thread about packaging 'sent'.
> 
> > 
> > I agree my version is less accurate, but it acts like a summing up and
> > (actually) is precisely the way I look at these statements. We can
> > have both. I am not saying we should replace your section.
> 
> I think we are all loath to include inaccuracies in the manual. But on
> the other hand, I think we need to find a way to summarize the
> distinction that is close to what Pjotr is proposing.
> 
> Some of us have an understanding of the subject that is directly based
> on the Guix / Nix source code. The rest of us have learned by
> trial-and-error and rough heuristics like Pjotr's summary (hopefully we
> will all 'use the source' eventually ;) .
> 
> The difficult thing is explaining it in a way that "sets up" the reader
> for further learning. You must be accurate, but you must not be too
> verbose, because when you are banging your head against the wall, it is
> difficult to read a long text.
> 
> The other day, this helpful jewel was shared by mark_weaver on #guix [0]:
> fhmgufs: the distinction between build and runtime dependencies is
> determined by scanning the outputs of the build for references to
> /gnu/store/....
> 
> Learning the mechanism made it clear to me. This is why Python inputs
> must be propagated: there is nowhere in the main Python program to link
> to dependencies in the store, so the inputs must be propagated onto
> PYTHONPATH. I already understood the difference between 'native-inputs'
> and 'inputs', and this doesn't really get to the heart of the
> difference, but it does draw a line between them.
> 
> I propose we adapt this statement for use in the manual (assuming that
> is accurate).
> 
> If there is no updated patch in a few hours, I will write one, but I
> can't do it at the moment.
> 
> [0]
> https://gnunet.org/bot/log/guix/2015-12-09
> 
> PS— I can't follow the "flow" of this conversation because some people
> are replying in-line while others are top-posting. Please, let's pick
> one (I vote for in-line).
> 
> > 
> > Anyway, maybe I am the only one seeing it like this.
> > 
> > Pj.
> > 
> > On Mon, Dec 14, 2015 at 09:58:19AM +0100, Ludovic Courtès wrote:
> > > Pjotr Prins <pjotr.public12@thebird.nl> skribis:
> > > 
> > > > Thanks Ludo. I still think it could be made a little clearer from the packager's 
> > > > perspective. How about concluding it with something like:
> > > >
> > > > In short, to create a package, by default you should use 'inputs' for
> > > > dependencies. Use 'native-inputs' for tools used at build-time, but
> > > > not at runtime and use propagated-inputs when the other two do not
> > > > suffice.
> > > 
> > > This is certainly shorter, but the problem I have with that is that it
> > > does not accurately explain what’s going on.  The current text is
> > > admittedly more verbose, but I think it is more accurate.
> > > 
> > > Hope that makes sense.
> > > 
> > > Ludo’.
> > > 
> > 
> > -- 
> > 
> 

-- 

Re: package dependencies

[Ludovic Courtès]

Pjotr Prins <pjotr.public12@thebird.nl> skribis:

> Another way to go about this is to create a manual for packagers. My
> guix-notes is more general (mostly to help my memory), and then there
> is the wiki-thing. But I agree we don't have a very helpful starting
> point for packagers considering they need to learn multiple things at
> the same time (not least Guile ;).

The “Defining Packages” section is meant to be some sort of a “getting
started” section for packagers, with cross-references to various more
in-depth sections.

IMO it would be ideal to fix it to actually fulfill that goal.  So I
hereby solicit patches that go in that direction!  :-)

Ludo’.

Re: package dependencies

[Ludovic Courtès]

ludo@gnu.org (Ludovic Courtès) skribis:

> Leo Famulari <leo@famulari.name> skribis:
>
>> On Sun, Dec 13, 2015 at 02:45:46PM +0100, Ludovic Courtès wrote:
>>> Hello!
>>> 
>>> I’ve rephrased the doc in “package Reference” in a way that is hopefully
>>> clearer:
>>> 
>>>      ‘inputs’ (default: ‘'()’)
>>>      ‘native-inputs’ (default: ‘'()’)
>>>      ‘propagated-inputs’ (default: ‘'()’)
>>>           These fields list dependencies of the package.  Each one is a
>>>           list of tuples, where each tuple has a label for the input (a
>>>           string) as its first element, a package, origin, or derivation
>>>           as its second element, and optionally the name of the output
>>>           thereof that should be used, which defaults to ‘"out"’ (*note
>>>           Packages with Multiple Outputs::, for more on package
>>>           outputs).  For example, the list below specifies 3 inputs:
>>> 
>>>                `(("libffi" ,libffi)
>>>                  ("libunistring" ,libunistring)
>>>                  ("glib:bin" ,glib "bin"))  ;the "bin" output of Glib
>>> 
>>>           The distinction between ‘native-inputs’ and ‘inputs’ is
>>>           necessary when considering cross-compilation.  When
>>>           cross-compiling, dependencies listed in ‘inputs’ are built for
>>>           the _target_ architecture; conversely, dependencies listed in
>>>           ‘native-inputs’ are built for the architecture of the _build_
>>>           machine.
>>> 
>>>           ‘native-inputs’ is typically where you would list tools needed
>>>           at build time but not at run time, such as Autoconf, Automake,
>>>           pkg-config, Gettext, or Bison.  ‘guix lint’ can report likely
>>>           mistakes in this area (*note Invoking guix lint::).
>>> 
>>>           Lastly, ‘propagated-inputs’ is similar to ‘inputs’, but the
>>>           specified packages will be force-installed alongside the
>>>           package they belong to (*note ‘guix package’:
>>>           package-cmd-propagated-inputs, for information on how ‘guix
>>>           package’ deals with propagated inputs.)
>>> 
>>>           For example this is necessary when a library needs headers of
>>>           another library to compile, or needs another shared library to
>>>           be linked alongside itself when a program wants to link to it.
>>
>> I think it's a good improvement! This is a big obstacle for new
>> packagers.
>>
>> It may be worth linking between the sections about propagated-inputs and
>> the python-build-system, since the situation is somewhat different
>> there. At least in a footnote.
>
> Good point.  How about the patch below?  I’m not sure whether/how to
> cross-reference from ‘python-build-system’ & co. since they don’t
> mention the problem.

Pushed as e0508b6.

Ludo’.

Packagers tutorial, deployment tutorial

[Pjotr Prins]

In addition to the a packaging tutorial, I would also like a
deployment tutorial where explain how to do system configuration and
how to create a caching server/build server in a few steps.

The information is there in the main docs (and source code), but what
we lack is a short descriptive list what steps one has to go through.

Ludo, I am happy to participate in this effort. I would like to
propose using org-mode on for the initial versions. Simply because I
am productive that way.

Would that be OK? And, despite my own reservations on github's growing
role, I think at this stage github has the best functionality. Also
github invites contributions because many people are signed up. For
the short term, I suggest we use github for the tutorials. Github has
the right audience for readers too. Once it stabalizes it could go
into the main Guix tree.

Pj.

PS I don't like wiki's. Those are no option. 

Re: Packagers tutorial, deployment tutorial

[Ludovic Courtès]

Pjotr Prins <pjotr.public12@thebird.nl> skribis:

> In addition to the a packaging tutorial, I would also like a
> deployment tutorial where explain how to do system configuration and
> how to create a caching server/build server in a few steps.
>
> The information is there in the main docs (and source code), but what
> we lack is a short descriptive list what steps one has to go through.

When Florian (fps) was trying to build everything on his machine, we
noticed that yeah, it’s easily done via a couple of Bash lines that call
out to ‘guix build’ and the likes, but we should really provide a
specific command for that, like ‘guix build --all’, at least.

People could set up Hydra, and we could provide GuixSD configurations
that do that (we’ll have to anyway, for the new front-end server), but
that’s too much of a sledgehammer for use cases such as Florian’s.

> Ludo, I am happy to participate in this effort. I would like to
> propose using org-mode on for the initial versions. Simply because I
> am productive that way.

I really think this kind of information should go in the canonical
manual.  “Defining Packages” and “Using the Configuration System” were
intended this way.  I understand they are currently badly structured and
incomplete, but I think we should fix them.

Having a single canonical place for documentation is very important to
me.  This is too often dismissed in favor of chaotic documentation
spread over several random places.

For someone willing to contribute non-trivial documentation, I cannot
imagine Texinfo being a significant barrier.  For the most part, it’s
really trivial.

WDYT?

> Would that be OK? And, despite my own reservations on github's growing
> role, I think at this stage github has the best functionality. Also
> github invites contributions because many people are signed up. For
> the short term, I suggest we use github for the tutorials. Github has
> the right audience for readers too. Once it stabalizes it could go
> into the main Guix tree.

You can use GitHub for your own work if you want, of course.  However,
Guix itself will remain on Savannah, and its procedure will remain
patches sent over email.

I am fine with discussing improvements to our procedures, and I think
it’s important to remain critical.  However, promoting GitHub/GitLab,
their proprietary software, and their inevitable attacks on user privacy
is a no-go for me.

Thanks,
Ludo’.

Re: Packagers tutorial, deployment tutorial

[Pjotr Prins]

On Thu, Dec 17, 2015 at 02:01:37PM +0100, Ludovic Courtès wrote:
> For someone willing to contribute non-trivial documentation, I cannot
> imagine Texinfo being a significant barrier.  For the most part, it’s
> really trivial.
> 
> WDYT?

Texinfo is quite a bit harder to read/write than Org-mode. I understand your
point about central canonical documentation - and, indeed, that is
where it should end if it is any good.

For drafting tutorials, however, I prefer a more loose approach. Think
of it as a form of blogging. And when parts of it are good enough they
may end up in the main docs. 

> You can use GitHub for your own work if you want, of course.  However,
> Guix itself will remain on Savannah, and its procedure will remain
> patches sent over email.

I am not questioning that. I am talking about writing tutorials. 

Anyway, I don't hear much enthusiasm for such a project.

Pj.
-- 

Re: Packagers tutorial, deployment tutorial

[Ludovic Courtès]

Pjotr Prins <pjotr.public12@thebird.nl> skribis:

> Anyway, I don't hear much enthusiasm for such a project.

I think I insisted too much on my concerns, making it sound negative;
sorry about that.

I am definitely enthusiastic about improving documentation.  I think
there’s some consensus that the manual in its current form is
insufficient, so efforts in that direction are more than welcome!

Ludo’.

Re: Packagers tutorial, deployment tutorial

[Christopher Allan Webber]

Ludovic Courtès writes:

> Pjotr Prins <pjotr.public12@thebird.nl> skribis:
>
>> Anyway, I don't hear much enthusiasm for such a project.
>
> I think I insisted too much on my concerns, making it sound negative;
> sorry about that.
>
> I am definitely enthusiastic about improving documentation.  I think
> there’s some consensus that the manual in its current form is
> insufficient, so efforts in that direction are more than welcome!
>
> Ludo’.

Yes, I just had conversations with one person today who was frustrated
trying to learn how to build their first package and lamenting the lack
of an official tutorial.

I'd love to see something more tutorial'y.  I'd be happy to provide some
feedback to it.

As for format to use, Pjotr, have you considered using Skribilo?

  http://www.nongnu.org/skribilo/

It has the advantage of being written in Guile, having nice HTML and
Texinfo exports, having an orgmode-like reader (a bit less powerful but
still nice), and having a delightful sk-expressions format with Skribe
(I was totally skeptical of sk-expressions but am now 100% on board).

  https://notabug.org/cwebber/guile-tutorial/

I've been really enjoying it.

Anyway, yes, please do work on these tutorials! :)
 - Chris

Re: Packagers tutorial, deployment tutorial

[Leo Famulari]

On Thu, Dec 17, 2015 at 04:58:15PM -0600, Christopher Allan Webber wrote:
> Ludovic Courtès writes:
> 
> > Pjotr Prins <pjotr.public12@thebird.nl> skribis:
> >
> >> Anyway, I don't hear much enthusiasm for such a project.
> >
> > I think I insisted too much on my concerns, making it sound negative;
> > sorry about that.
> >
> > I am definitely enthusiastic about improving documentation.  I think
> > there’s some consensus that the manual in its current form is
> > insufficient, so efforts in that direction are more than welcome!
> >
> > Ludo’.
> 
> Yes, I just had conversations with one person today who was frustrated
> trying to learn how to build their first package and lamenting the lack
> of an official tutorial.

I had this same reaction during my first packages, but I forgot once I
learned. It's worth trying to put oneself in the beginner's mind and I'd
like to help. I'll use whatever platform as long as the goal is to move
the final product somewhere that's not closed like Github.

Re: Packagers tutorial, deployment tutorial

[Christopher Allan Webber]

Leo Famulari writes:

> On Thu, Dec 17, 2015 at 04:58:15PM -0600, Christopher Allan Webber wrote:
>> Ludovic Courtès writes:
>> 
>> > Pjotr Prins <pjotr.public12@thebird.nl> skribis:
>> >
>> >> Anyway, I don't hear much enthusiasm for such a project.
>> >
>> > I think I insisted too much on my concerns, making it sound negative;
>> > sorry about that.
>> >
>> > I am definitely enthusiastic about improving documentation.  I think
>> > there’s some consensus that the manual in its current form is
>> > insufficient, so efforts in that direction are more than welcome!
>> >
>> > Ludo’.
>> 
>> Yes, I just had conversations with one person today who was frustrated
>> trying to learn how to build their first package and lamenting the lack
>> of an official tutorial.
>
> I had this same reaction during my first packages, but I forgot once I
> learned. It's worth trying to put oneself in the beginner's mind and I'd
> like to help. I'll use whatever platform as long as the goal is to move
> the final product somewhere that's not closed like Github.

Yes, could we contribute in some way that would allow us to submit
patches or branches on this mailing list?  Would that be okay both from
a guix-devel maintainer perspective and from a Pjotr starting the docs
perspective?

Re: Packagers tutorial, deployment tutorial

[Pjotr Prins]

On Thu, Dec 17, 2015 at 04:58:15PM -0600, Christopher Allan Webber wrote:
> Yes, I just had conversations with one person today who was frustrated
> trying to learn how to build their first package and lamenting the lack
> of an official tutorial.

Easy as it looks ;). But yes, I'd champion a stepwise introduction.
And a somewhat more advanced treatment of creating a builder, for
example. I mean, that is the exciting stuff :)

> As for format to use, Pjotr, have you considered using Skribilo?

I looked into it earlier. It is an option, for sure. Maybe we should
start out with that and see if it works. I think it is attractive it
is Guile. I wrote something similar in Ruby to write my PhD thesis
(and journal papers), so I understand the need of such a translator
:).

OK, we can take FOSDEM as an opportunity to kick-start if we haven't
by then.

Pj.

Re: Packagers tutorial, deployment tutorial

[Christopher Allan Webber]

Pjotr Prins writes:

>> As for format to use, Pjotr, have you considered using Skribilo?
>
> I looked into it earlier. It is an option, for sure. Maybe we should
> start out with that and see if it works. I think it is attractive it
> is Guile. I wrote something similar in Ruby to write my PhD thesis
> (and journal papers), so I understand the need of such a translator
> :).
>
> OK, we can take FOSDEM as an opportunity to kick-start if we haven't
> by then.
>
> Pj.

Great, I'll be at the Guile room at FOSDEM for most of the time, I'd
love to talk about it!