Re: Blog: Guix packaging tutorial

[ludo@gnu.org (Ludovic Courtès)]

Hi Pierre,

Thanks a lot for writing this tutorial!  I think it’ll be very useful to
many.

Pierre Neidhardt <mail@ambrevar.xyz> skribis:

> Let me know if it's approachable enough and if you find any missing/tangled
> parts in the progression.

I’m not in a good position to say if it’s approachable I’m afraid.  :-)
It would be nice to get feedback from newcomers or users of other
packaging tools.

It’s a bit long indeed, but I think it covers lots of useful things,
going from simple packages to more complex things.  So overall I think
it’s very good and nicely complements our doc!

Some inline comments below, but nothing crucial.

> #+TITLE: Guix packaging tutorial
> #+AUTHOR: Pierre Neidhardt
> #+date: <2018-09-24 Mon>

[...]

> Package definitions are also written in Scheme, which empowers Guix in some very

Perhaps link to
<https://www.gnu.org/software/guix/manual/en/html_node/Defining-Packages.html>.
This part overlaps with the “Defining Packages” section, but it probably
doesn’t hurt.

> unique ways, unlike most other package managers that use shell scripts or
> simplistic languages.

s/simplistic/simple/ (let’s not be judgmental)

> - build-system :: This is where the power of abstraction provided by the Scheme
>                   language really shine: in this case, the ~gnu-build-system~

s/shine/shines/

>                   the ~emacs-build-system~, and many more.

[[https://www.gnu.org/software/guix/manual/en/html_node/Build-Systems.html][and many more]]

> Guix uses the Guile implementation of Scheme.  To start playing with the
> language, install it with ~guix package --install guile~ and start a [[https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop][REPL]] by
> running ~guile~ from the commandline.

s/commandline/command line/

Maybe link to
<https://www.gnu.org/software/guile/manual/html_node/Using-Guile-Interactively.html>
for the REPL.

> - The keyword syntax is ~#:~, it is used to create unique identifiers.  See also
>   http://practical-scheme.net/wiliki/schemexref.cgi?keyword%3F.

Rather link to
<https://www.gnu.org/software/guile/manual/html_node/Keywords.html> as
each Scheme has its own flavor of keywords…

> - The percentage ~%~ is conventionally used as a prefix for variables generated
>   in scope.

s/conventionally.*/typically used for read-only global variables/

(it’s a disputed convention :-))

> *** GUIX_PACKAGE_PATH

You’ll have to mention that the upcoming Guix version features a new
mechanism, “channels”, which provides better integration and provenance
tracking than ‘GUIX_PACKAGE_PATH’.  :-)

> *** Direct checkout hacking
>
> Working directly on the Guix project is recommended: it reduces the friction
> when the time comes to submit your changes upstream to let the community benefit
> from your hard work!
>
> Check out the official [[https://git-scm.com/][Git]] repository:
>
> #+BEGIN_SRC sh
> $ git clone https://git.savannah.gnu.org/git/guix.git
> #+END_SRC

Maybe we should mention that the repo contains both
Guix-the-tools/libraries and the package definitions?  This often comes
as a surprise to people used to toolsets where both are clearly
separate, such as APT vs. Debian packages.


[...]

>       (build-system gnu-build-system)
>       (native-inputs
>        `(("pkg-config" ,pkg-config)))
>       (inputs
>        `(("libbsd" ,libbsd)
>          ("ncurses" ,ncurses)))
>       (propagated-inputs
>        `(("mg-extensions"
>           ,(origin
>              (method url-fetch)
>              (uri "https://example.org/~doe/mg-extensions.tar.gz"
>              (sha256
>               (base32
>                "0kfhpj5rnh24hz2714qhfmxk281vwc2w50sm73ggw5d15af7zfsw"))))))

It doesn’t make much sense to propagate a tarball, does it?

>       (arguments
>        '(#:tests? #f ; No test suite available.
>          #:make-flags (list (string-append "prefix=" %output)
>                             "CC=gcc")
>          #:configure-flags `(,(string-append "--with-ext="
>                                              (assoc-ref %build-inputs "mg-extensions")))

I recommend using ‘list’ rather than quasiquote/unquote here.

> There are 3 different input types.  In short:

Perhaps link to
<https://www.gnu.org/software/guix/manual/en/html_node/package-Reference.html>?

> ** Code staging
>
> The astute reader may have noticed the quasi-quote and comma syntax in the
> argument field.  Indeed, the build code in the package declaration should not be
> evaluated on the client side, but only when passed to the Guix daemon.  This
> mechanism of passing code around two running processes is called [[https://arxiv.org/abs/1709.00833][code staging]].
> See [[https://www.gnu.org/software/guix/manual/en/html_node/G_002dExpressions.html][the "G-Expressions" chapter]] from the manual.

Though precisely package definitions don’t use gexps yet…  Not sure if
we should mention it; maybe it’s outside the scope of this tutorial.

> ** Module prefix
>
> The license now needs a prefix: this is because of how the ~license~ module was
> important in the package, as ~#:use-module ((guix licenses) #:prefix
> license:)~.  This gives the user full control over namespacing.

Perhaps mention that the prefix is needed to avoid classes between,
say, the ‘zlib’ variable from licenses.scm and the ‘zlib’ variable from
compression.scm?

Perhaps you can link to
<https://www.gnu.org/software/guile/manual/html_node/Using-Guile-Modules.html>.

> See https://guix.info/contact/ for the mailing lists, IRC, etc.

For now please use gnu.org/software/guix URLs.

> * References
>
> - [[https://gitlab.com/pjotrp/guix-notes/blob/master/HACKING.org][Pjotr’s hacking guide to GNU Guix]]
>
> - "Guix Guix: Package without a scheme!", by Andreas Enge (in
>   =guix-maintenance.git/talks/ghm-2013/andreas/slides.pdf=)

And the “Defining Packages” section of the manual!  ;-)

Thank you!

Ludo’.