Re: [PATCH guix-artwork v2] website: posts: Add Dissecting Guix, Part 1: Derivations.

[Ludovic Courtès]

Hello,

"(" <paren@disroot.org> skribis:

> * website/posts/dissecting-guix-1-derivations.md: New blog post.

Neat!  I think your plan for blog posts is really great; I’m sure it
will be of great use to many.

Perhaps we could schedule the first one a few days after the release
(which should be on Monday, 19th)?

And then schedule subsequent posts once per month or something?

Anyway, I like this first post!  Here are cosmetic suggestions:

> +These concepts were originally described by Eelco Dolstra, the author of 
> Nix, in

s/author/original author/

> +# `.drv` Files
> +
> +You've probably seen these being printed by the Guix CLI now and again.

Please avoid abbreviations; if you want to use them, you can write “Guix
command-line interface (CLI)” the first time and just “CLI” on
subsequent iterations.  Some abbreviations may look obvious to us, but I
think it’s important to reduce assumptions about what the reader already
knows, especially since the goal is to help them learn.

> +Derivations, represented in the daemon's eyes by `.drv` files, contain
> +instructions for building store items.  We can retrieve the paths of these
> +`.drv` files with the `guix build --derivations` command:

Perhaps you can add a paragraph showing package definitions, explaining
that they get “lowered” to derivations, but that packagers and users
only ever manipulate high-level objects such as packages or operating
systems, not derivations?

> +The procedure we use to turn a high-level object like `<package>` into a
> +derivation is called `lower-object`; more on that in a future post.  However,
> +this doesn't produce a derivation:
> +
> +```scheme
> +(pk (lower-object irssi))
> +;;; (#<procedure 7fe17c7af540 at guix/store.scm:1994:2 (state)>)
> +```

Maybe beforehand you can mention “,lower irssi”, to show that it exists
and that there’s a simple way to peek at derivations, and only then
dissect “,lower”?

> +The returned object is a procedure that needs to be evaluated in the context 
> of

s/is a procedure/is a monadic value [in the store monad](…)/

> +a store connection.  We do this by first using `with-store` to connect to the
> +store and bind the connection to a name, then wrapping the `lower-object` 
> call
> +with `run-with-store`:
> +
> +```scheme
> +(define irssi-drv
> +  (pk (with-store %store
> +        (run-with-store %store
> +          (lower-object irssi)))))
> +;;; (#<derivation 
> /gnu/store/zcgmhac8r4kdj2s6bcvcmhh4k35qvihx-irssi-1.4.3.drv => 
> /gnu/store/v5pd69j3hjs1fck4b5p9hd91wc8yf5qx-irssi-1.4.3 7fe1902b6140>)
> +
> +(define glib-drv
> +  (pk (with-store %store
> +        (run-with-store %store
> +          (lower-object glib)))))
> +;;; (#<derivation 
> /gnu/store/81qqs7xah2ln39znrji4r6xj85zi15bi-glib-2.70.2.drv => 
> /gnu/store/lp7k9ygvpwxgxjvmf8bix8d2aar0azr7-glib-2.70.2-bin 
> /gnu/store/22mkp8cr6rxg6w8br9q8dbymf51b44m8-glib-2.70.2-debug 
> /gnu/store/a6qb5arvir4vm1zlkp4chnl7d8qzzd7x-glib-2.70.2 
> /gnu/store/y4ak268dcdwkc6lmqfk9g1dgk2jr9i34-glib-2.70.2-static 7fe17ca13b90>)
> +```

Personally I’d leave ‘with-store’, ‘run-with-store’, and ‘lower-object’
for a subsequent post, to avoid muddying the waters.  In this one I’d
just use “,lower” and “,build”, which is enough to peek at derivations
(we discussed it earlier on IRC and ISTR you were not quite convinced
though :-)).

> +Derivations are one of Guix's most important concepts, but are fairly easy to

Maybe: 
[Derivations](https://guix.gnu.org/manual/devel/en/html_node/Derivations.html)

> +4. `derivation-system`, specifying the Nix system a derivation will be 
> compiled
> +   for

s/Nix system(.*)/system type\1—e.g., `"x86_64-linux"`/

This is great, thanks a lot for your work!

Ludo’.