[bug#62356] [PATCH guix-artwork] website: posts: Add Dissecting Guix, Part 3: G-Expressions.

[Simon Tournier <zimon.toutoune@gmail.com>]

Hi,

Cool!  Thanks, it’s very helpful.

Minor comments.

On mar., 21 mars 2023 at 20:57, "\( via Guix-patches" via <guix-patches@gnu.org> wrote:

[...]

> +The shortcomings of using s-expressions in this way are numerous: we have to
> +convert everything to a derivation before using it, and _inputs are not an
> +inherent aspect of the builder_.  G-expressions were designed to overcome these
> +issues.

Here I would link to the paper introducing G-expressions,

    https://hal.inria.fr/hal-01580582v1


> +# Premortem Examination

[...]

> +Here's an example gexp that is essentially equivalent to our `sexp-builder`:
> +
> +```scheme
> +(use-modules (guix gexp))
> +
> +(define gexp-builder
> +  #~(symlink #$(file-append irssi "/bin/irssi")
> +             #$output))
> +```
> +
> +`gexp-builder` is far more concise than `sexp-builder`; let's examine the syntax
> +and the `<gexp>` object we've created.  To make a gexp, we use the `#~` syntax,
> +equivalent to the `gexp` macro, rather than the `quasiquote` backtick used to
> +create sexps.
> +
> +When we want to embed values from outside as references, we use `#$`, or
> +`ungexp`, which is, in appearance if not function, equivalent to `unquote`
> +(`,`).  `ungexp` can accept any of four reference types:

Well, maybe it is a bit stretching and is probably not natural at all
but I would try to introduce some unquote in sexp-builder.  I think it
would help to see the parallel between S-exp and G-exp; well how G-exp
extend S-exp as you explained in the introduction.

> 
> +- Sexps (strings, lists, etc), which will be embedded literally.

From a stylistic point of view, I would write ’S-expressions’ in plain
and not S-exps or sexps…

> +- Other gexps, embedded literally.

…Similarly for G-expression.  Both over all the post.  Except when it
refers to code as ’gexp-builder’.


> +That's a lot of complexity abstracted away!  For more complex packages and
> +services, especially, gexps are a lifesaver; you can refer to the output paths
> +of inputs just as easily as you would a string constant.  You do, however, have
> +to watch out for situations where `ungexp-native`, written as `#+`, would be
> +preferable over regular `ungexp`, and that's something we'll discuss later.

Before the brief digression, I would do another. ;-)  Mention ,build and
,lower from “guix repl”.

> +A brief digression before we continue: if you'd like to look inside a `<gexp>`

[...]

> +# The Lowerable-Object Hardware Shop

[...]

> +There are many other useful lowerable objects available as part of the gexp
> +library.  These include `computed-file`, which accepts a gexp that builds
> +the output file, `program-file`, which creates an executable Scheme script in
> +the store using a gexp, and `mixed-text-file`, which allows you to, well, mix
> +text and lowerable objects; it creates a file from the concatenation of a
> +sequence of strings and file-likes.  The
> +[G-Expressions](https://guix.gnu.org/manual/en/html_node/G_002dExpressions.html)
> +manual page has more details.

Maybe, I would start another section here; or split with 2 subsections.

> +So, you may be wondering, at this point: there's so many lowerable objects
> +included with the gexps library, surely there must be a way to define more?
> +Naturally, there is; this is Scheme, after all!  We simply need to acquaint
> +ourselves with the `define-gexp-compiler` macro.

[...]

> +Let's try this out now:
> +
> +```scheme
> +(use-modules (gnu packages vim))
> +
> +(define script-directory-output
> +  (build-derivation
> +   (lower-object
> +    (script-directory
> +     #~'(("irc" . #$(file-append irssi "/bin/irssi"))
       ---^

Hum, maybe #~' needs an explanation.  Well, using G-expressions, I am
missing why Schemers are complaining about Haskell syntax. ;-)

> +         ("editor" . #$(file-append neovim "/bin/nvim")))))))
> +
> +(scandir (string-append script-directory-output "/bin"))
> +⇒ ("." ".." "editor" "irc")
> +```
> +
> +Who knows why you'd want to do this, but it certainly works!  We've looked at
> +why we need gexps, how they work, and how to extend them, and we've now only got
> +two more advanced features to cover: cross-build support, and modules.

Here, I would link to another introduction of G-expression,

    https://archive.fosdem.org/2020/schedule/event/gexpressionsguile/

or maybe in the Conclusion section.

> +# Importing External Modules

[...]

> +```scheme
> +(define silly-directory-output

Maybe instead of ’silly’, I would pick another name as ’simple’ or
’empty’ or ’trivial’ or ’not-serious’ or else. :-)

And similarly for snippets from above.


> +# Conclusion
> +
> +Mastering gexps is essential to understanding Guix's inner workings, so the aim
> +of this blog post is to be as thorough as possible.  However, if you still find
> +yourself with questions, please don't hesitate to stop by at the IRC channel
> +`#guix:libera.chat` and mailing list `help-guix@gnu.org`; we'll be glad to
> +assist you!

Maybe, you could link to Arun’s or Marius’s posts; for the ones I am
aware of. :-)

https://www.systemreboot.net/post/deploy-scripts-using-g-expressions
https://gexp.no/blog/guix-drops-part-3-g-expressions.html


Cheers,
simon