Re: Trying to contribute packages: ./pre-inst-env doesn't work

[Doron Behar]

On Wed, May 15, 2019 at 11:26:08PM +0200, Ricardo Wurmus wrote:
> It compiles Guile modules.  Using compiled modules is faster than having
> to interpret everything.  You can try without compiling changed modules
> but the performance penalty when you have lots of interpreted modules
> will likely be hard to tolerate.
> 
> 
> This is a surprising statement and naturally I disagree with it :)  I
> suggest to take a step back when the frustration of learning something
> new makes you want to say harsh things.

You are right. I'm not frustrated anymore. I have been fighting this for
many hours without taking a break and this probably made me angry. I'm
ashamed now that I wasn't aware of that I felt that way because I was
tired and hungry..

And please don't get me wrong. Overall, with all my heart, I find
Guix's design magnificent! So you wrote:

> Packages in Guix are Scheme values bound to variable names.  Packaging
> is a simple form of programming.

This is definitely the right way to implement a functional package
manager. TBH, I've had this kind of idea in the past for a package
manager with very similar feature set as Guix's and while it was cooking
in my head I've had no idea GNU implemented it already so well.
Therefor, I'm thrilled that I get the chance to contribute to it. I just
never expected it to be so hard right at the beginning. Also, I've had
no idea how complicated the implementation for this idea might become
but I'm certain it is justified.

> > Plus, do I have to run make after every change to a package definition!?
> > Will it compile everything from the ground up after every such change? I
> > wish these technical details would have been documented...
> 
> “make” does not cause recompilation of unchanged things.  This is
> not particular to Guix, so it’s not documented as part of Guix.
> 

This is a good demonstration for a lack of technical details in the
documentation I think needs to be addressed so that hopefully, common
and simple help requests in this list won't be as common.

I've quiet a lot of experience with *using* the Gnu build system (not
with *developing* with it) and the whole `./configure && make && make
install` procedure. Notably, I've gained that experience from packaging
software for Arch Linux. Therefor, I knew that `make` doesn't recompile
everything and that it checks the modification date of compiled files vs
the source files etc.

However, I didn't assume that this characteristic of `make` applies to a
project that uses Guile. This might seem obvious to Guile experts like
you but for newbies / newcomers like me, Guile is a strange creature
with a hard to learn syntax, not to mention my unfamiliarity with it's
ecosystem. Therefor, TBH, it's quiet terrifying. As a hobbyist
programmer like me who've had experience only with common languages like
Python, Go, Bash, Lua, C and C++, Guile has a very steeping learning
curve for me.

Perhaps this design choice is not bad from a technical point of view,
but it is certainly not inviting contributers. Therefor, especially if
we profess that "Packaging is a simple form of programming", packages
contributers need to be introduced officially, inside the Guix
documentation to Guile.

The following is a rough description of the way I have in mind for how
to improve the documentation pretty much from the ground up. It doesn't
consist only of adding more information but also changing the order in
which the subjects are presented.

------

Under section 14 (Contributing), the first subsection should address
package contributers because this is the most common type of
contributers. This section (14.1) should assume no programming
experience but only certain system administration experience, which will
include:

- Command line usage.
- Editing text files with a command line editor.
- Awareness of how environment variables might influence a program's
  behaviour.

After this assumption stated, an introduction to the following should be
given[1]:

- What is a build systems?
- How Guix uses the common characteristics of all Build systems to build
  packages using all used build systems in a similar manner (phases..).
- Because Guix uses it, introducing the Gnu build system in particular:
  * What does `./configure`?
  * How `make` works?
  * Why does sometimes `./configure` is not available and `./bootstrap`
    (or sometimes `autoreconf -vfi`) is needed.

That said, I think parts of section 6 (Programming Interface) relevant
to package definitions, should be merged with the new version of the new
subsection 14.1; and the rest of it should be moved to the bottom of the
whole manual so packaging guidelines should be as concise as possible.

The following part of subsection 14.1 should explain concisely how to
setup an environment suitable for packages contribution. This should
include stating clearly that it might take a while and a lot of CPU but
it is unavoidable and it will only be needed to be done once.

The instructions should be accompanied with an explanation of what each
command does and exactly why it is needed and why they will be needed or
not in the future when you'll add new packages. This accompanying
information should assume the reader has read the introduction to build
systems from above[1]. Summarizing:

- guix environment guix
- ./bootstrap 
- ./configure - using the flags given to it when Guix (from wherever you
  got it) was built - very important to make this standout.
- make - important to note that this takes a while but since make
  doesn't recompile everything every time this should be done only once.

Afterwards, an introduction to Guile in general and particularly for
programming new packages should be given, with the following subjects:

- What is functional programming.
- A Syntax Crash course with links to the official reference.
- Guile's ecosystem:
  * The compiler's usage syntax.
  * What is it's "bytecode".
  * Environment variables used by the compiler.
- How Guile is used in combination with the Gnu build system in Guix's
  repo.

------

This is an rough summarize of what I've cooked in mined as for how to
improve the documentation. I hope this brings back some of the respect I
lost after my impolite rants in my previous replies (I hope I'm forgiven
now :)).

Please let me know what do you think Ricardo. I can forward or Cc this
to guix-devel but I'd be happy to know your opinion first.

Regards, Doron.