Re: Best practices for writing services

[Maxim Cournoyer]

Hi Xinglu,

Xinglu Chen <public@yoctocell.xyz> writes:

> Hi Guix,
>
> I am going to write an mcron service for `guix home`[1][2] and before
> proceding, I would like to get some suggestions on what the best
> practices are for writing services in Guix.
>
> Currently there seems to be two main ways to do this, the first one
> is the define one or more records for the configuration field of a
> service using `define-record-type*`, see the tor service in (gnu
> services networking) for example.  The other method is to use
> `define-configuration` to declare the configuration fields of a service,
> see the transmission service in (gnu services file-sharing) for example.
>
> The first method seems to be the more common one but the developer
> usually has to write a lot of things manually.  The "real" configuration
> file for the program or is usually created by concatenating a bunch of
> strings and the developer has to write documentation for all the
> configuration fields manually.
>
> The second method removes quite a lot of boilerplate and the developer
> will define different serializers that convert scheme syntax like lists,
> alist, boolean... to the "real" configuration syntax of the program.  It
> also does some automatic typechecking to some degree and allows the
> developer to write docstrings for each configuration field.  There is
> then a procedure called `generate-documentation` which can automatically
> generate texinfo documenation from the docstrings.
>
> I couldn't find any information in the manual regarding what conventions
> should be used when writing services for Guix and would like to hear
> from more experienced Guix hackers what the best practices are.

That's a very good question, which I asked myself recently when
attempting to write my first non-trivial service for Guix
(jami-daemon-service-type).  I'd say 'define-configuration' is
technically superior because of the automatic type checking it provides.
It's also neat to be able to define the doc at one place and
auto-generate it (although that's still manual for now).  It has
definitely been collecting some dust compared to the simpler approach
using 'define-record-type*' directly, and the doc output it can generate
doesn't match what is currently the norm in the manual, so it'd need a
bit of a refresh.

Still, I see great potential for define-configuration.

Maxim