Re: guile scheme tutorial

[Ludovic Courtès]

Hello!

rendaw <address@hidden> skribis:

> The areas that were important for me but weren't well documented were:

Thanks for explaining!  That’s a lot of things to digest.  :-)

I’m not entirely sure I agree with or understand everything you mention,
I’ll comment on some of these below.  However, I think you should really
propose incremental improvements to the manual in these areas; it’ll be
easier to discuss specific sections or paragraphs.

> 1. Concepts
>
> * What is functional package management?  What is garbage collection? 
> How do these work?

“(guix) Managing Software the Guix Way” has a paragraph about functional
package management, but that’s (purposefully) the only place where FPM
is discussed.

> What is a package?  How does Guix determine what makes a package
> unique?  What's a derivation, and what's the relationship between
> derivations and packages?  The best I could find is that a derivation
> communicates an action to the store, but that uses vocabulary in ways
> that 99% of readers won't be familiar with ("communicate", "action",
> isn't the "store" a directory?) and is so abstract that it won't help
> people make choices dependent on that.  What's a tangible example of a
> derivation?  Where and why would someone use a derivation directly?

“(guix) Defining Packages” explains:

     Behind the scenes, a derivation corresponding to the ‘<package>’
  object is first computed by the ‘package-derivation’ procedure.  That
  derivation is stored in a ‘.drv’ file under ‘/gnu/store’.  The build
  actions it prescribes may then be realized by using the
  ‘build-derivations’ procedure (*note The Store::).

… with cross-references.

> The only gc documentation says that anything reachable from a root won't
> be deleted, but doesn't explain what a root is, how they're created, how
> they're identified, how they're removed, etc.

“(guix) Invoking guix gc” has a paragraph that I think explains what a
GC root is:

     The garbage collector has a set of known “roots”: any file under
  ‘/gnu/store’ reachable from a root is considered “live” and cannot be
  deleted; any other file is considered “dead” and may be deleted.  The
  set of garbage collector roots (“GC roots” for short) includes default
  user profiles; by default, the symlinks under ‘/var/guix/gcroots’
  represent these GC roots.  New GC roots can be added with ‘guix build
  --root’, for example (*note Invoking guix build::).  The ‘guix gc
  --list-roots’ command lists them.

> * What happens when running guix system?

How does “(guix) Using the Configuration System” fall short here?

> What does guix system do with the definition once it's returned?  How
> does install happen on a live system?  What stages are there in the install?
>
> How does this process change for the different install targets? (vm,
> disk-image, docker image, etc)

Likewise, how does “(guix) Invoking guix system” fail to explain this?

> * G-expressions
>
> The analogy to quotes is useful, but how do these actually work? 
> They're relocatable - how does one store them to disk?  Read them from
> disk an execute them?  Or execute them from memory?  Quotes can be
> converted back from data using `eval` - what's the g-expression
> equivalent?  Where can they be used (maybe this is more a reference
> thing - which functions take g-expression arguments)?

I think that “(guix) G-Expressions” answers some of these questions, but
perhaps you could propose a patch to clarify that.

Keep in mind that this section is not about the design and
implementation of G-Expressions—there’s a paper on that topic.  Instead,
the intent is to explain why they exist in the first place, and how they
can be used.

> * Package creation
>
> Again, the documentation says "use these build systems" but not why, or
> what they do.

“(guix) Build Systems” has:

  Each package definition specifies a “build system” and arguments for
  that build system (*note Defining Packages::).  This ‘build-system’
  field represents the build procedure of the package, as well as implicit
  dependencies of that build procedure.

I think that’s an good intro for “what they do”, no?

> IMO it would be better to start with the trivial build system, say "we
> have these files, here's how we turn it into a package" then show how
> the build systems make it much simpler but that they're just an
> extension of first principles.

I’m not sure.  I think as a packager you’re first and foremost
interested in ‘gnu-build-system’, ‘cmake-build-system’, and so on,
because those are the first you’ll use to get things done.
‘trivial-build-system’ is usually advanced usage.

> * Services
>
> I've been discussing this in another thread, but it's the same thing -
> what a service is is unclear because it hinges on the use of the word
> "extend" which isn't defined.

I think it does explain extensions in quite some detail, but Chris
concurs with you that it’s unclear, so I guess there’s room for
improvement.  :-)

In short, I’m sure there’s room for improvement in the manual.  I’m just
not sure what you are criticizing or suggesting.  That’s why I’d
encourage you to pick one specific example and post a patch for
discussion.  That would allow us to have a clearer understanding of how
we could improve things.

Thanks,
Ludo’.