Re: Blog: Guix packaging tutorial

[Ricardo Wurmus]

Hi Pierre,

thank you for writing this draft!  This is a good start.  Below are some
comments about the beginning and some general thoughts about the idea of
a tutorial.

> I'm not satisfied with the advanced example: I took ~mg~ because it has a lot 
> of
> typical customization (snippets, inputs, arguments) but it does not have
> - in-input sources
> - %build-inputs
> - propagated-inputs
>
> I've made up a "my-mg" package but it relies on made-up inputs, so it won't
> build.
> Better suggestions anyone?

I wonder if a complicated example like that really has a place in a
tutorial.  To me it seems a bit scary.  I image people who are used to
Conda to browse the tutorial and recoil in horror at seeing a
complicated example with all sorts of customizations.

Here some more comments:

> Want to rebuild everything from source for a specific
>   architecture?  Pass the ~#:system "YOUR-ARCH"~ argument to the list of
>   packages.

People would rather use the “--system” option on the command line
instead of overwriting the arguments field, I think, so maybe that’s not
a good example.

> =GNU hello= is a dummy project that serves as an idiomatic example for
> packaging.  If uses the GNU build chain (~./configure && make && make 
> install~).

s/If uses/It uses/

I would also replace “build chain” with “build system”.

> - source :: The ~origin~ record gather all the information required for a
>             source.  Among which:

How about: “This field contains a description of the source code origin.
The ~origin~ record contains these fields:” ?

> abstracts away the famous ~./configure && make && make
> install~ shell invocations: If the package can be built just
> those commands, then Guix can often handle the complete
> packaging process automatically. […]

“be built [+with] just those commands”.

What do you mean by “packaging process”?  What does Guix “handle” here?
I think it is less confusing to remove the sentence after the colon.

> - synopsis :: It should be a concise and explicit summary of what the package
>               does.  Many projects homepage already provide a synopsis, it's
>               fine to re-use it.

I’d remove “and explicit”.  I’d also remove the “Many projects
homepage..” sentence as we often tweak synopses to remove advertising
statements or to turn funny taglines into more informative, descriptive
statements.  You could also say “For many packages a tagline from the
project’s home page can be used as the synopsis.”

> dummy "my-hello", a copycat of the above declaration.

s/copycat/copy/

“copycat” is an imitator, not an imitation.

> Indeed, Guix refuses to build anything if the source fails to verify
> the checksum.

It isn’t clear here who verifies what.  The checksum and the source are
both passive in this situation, but the sentence makes it seem like the
source is active.  How about “if the given checksum does not match the
computed checksum of the source code”?

> To compute the correct checksum of the package declaration, we need to 
> download the
> source, compute the sha256 checksum and convert it to base32.

To avoid the duplication of “compute” let’s replace the first instance
with “obtain”.

> Thankfully Guix can automate this task for us, all we need is to
> provide the URI:

There should be a comma after the first word; I’d replace the comma
before “all” with a semicolon.

> update you =my-hello= declaration accordingly.

s/you/your/

> your desire to write more and more complex packages will grow

s/will grow/grows/

> returns an anonymous function, which can in turn be called over an argument:

Maybe better: “can in turn be applied to an argument:”

> Thus it enables us with fine-grained control over what is evaluated and what 
> is not.

s/enables/provides/

FWIW, I think that maybe we should avoid quasi-quotation in the
tutorial, or at least at this point.  It could be a little overwhelming
to be introduced to so many new concepts at once before seeing how they
might be useful.

Maybe this could be interleaved and motivated by packaging features.
For example, at the very beginning we define a package and then evaluate
it at the end so that we can use it with “guix package -f”.  Maybe it
would be better to avoid defining things and using the plain “package”
form.

Definitions could then be introduced later.

What do you think?

(I need to go now, but if you want I can comment on the next sections
tomorrow.)

--
Ricardo