Andrew Tropin <andrew@HIDDEN>
to control <at> debbugs.gnu.org.
Full text available.
Received: (at submit) by debbugs.gnu.org; 23 Dec 2021 13:22:42 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu Dec 23 08:22:42 2021
Received: from localhost ([127.0.0.1]:60636 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1n0O3N-0006yu-AK
for submit <at> debbugs.gnu.org; Thu, 23 Dec 2021 08:22:42 -0500
Received: from lists.gnu.org ([209.51.188.17]:33510)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <andrew@HIDDEN>) id 1n0O3K-0006ym-Dd
for submit <at> debbugs.gnu.org; Thu, 23 Dec 2021 08:22:39 -0500
Received: from eggs.gnu.org ([209.51.188.92]:33706)
by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <andrew@HIDDEN>) id 1n0O3J-0005Kl-JB
for guix-patches@HIDDEN; Thu, 23 Dec 2021 08:22:38 -0500
Received: from [2a00:1450:4864:20::134] (port=33679
helo=mail-lf1-x134.google.com)
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
(Exim 4.90_1) (envelope-from <andrew@HIDDEN>) id 1n0O3F-0007QW-JF
for guix-patches@HIDDEN; Thu, 23 Dec 2021 08:22:36 -0500
Received: by mail-lf1-x134.google.com with SMTP id k21so12450163lfu.0
for <guix-patches@HIDDEN>; Thu, 23 Dec 2021 05:22:30 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=trop-in.20210112.gappssmtp.com; s=20210112;
h=from:to:cc:subject:in-reply-to:date:message-id:mime-version;
bh=IzcJBaaTNMY0NS1nIJkKq6/J+O/SnAsYvjGnOHy+20g=;
b=NsvYm++PpKOLaO0XZIuQEkJn+URlM/782QZCcv36OzXuALtp7MlB6E06jNqolUGaF+
G+OXqGMUPwEyMB4A7HYCWNmcXWGouTrENyUgd02ownu+4YTS/Rmcmg2XG0x3T1z7tJ20
q85/To7sXC3J0Op4G99zKba/3ri7H0rKJ4boy7PULpxBNbKm3pYdTeysf5VoRQB7w8E4
V6IhowT/BqkP64AabtPjhGWCMZZyD+qDHqFbsz+kWevIuffJ+3LNUoHfc+Qwomtdcjo0
wcFRtP48caM9EhJ93cSwES+aUu8VfHr3zMGkpHgazftjMYV427lDGxu0ckKjjGpU766x
D7jg==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:from:to:cc:subject:in-reply-to:date:message-id
:mime-version;
bh=IzcJBaaTNMY0NS1nIJkKq6/J+O/SnAsYvjGnOHy+20g=;
b=SBNFXBdoufs73uy0g1/1rNCn09qJ4qaUkPs528Jnwd2vWqBvlEAddfxV3h+sFwAo+A
SFMxtm8v+HsSudL4jLYCicrAubpdjNOdyQYxIqRH+YnlPGJaZeOpDatR+4CN4lFtZYNB
JYY/B03iW0wLpVl2nn5j/WLyH0EzrkTyAOXzK9R3Ozwke3YMV3q12SW2FqSgoKuf8/I8
oRQ1xgYJKpEKlYn0tW1HHMp7aHMiyizdhptB0HvUUXj0oNoVW1vE8chH+829BXvXWQIo
9fMONLNjq4ZhhjNmx56gjR9rFHTDDOhGnmakqqKP2KulZTChSJR3NxhOGslbzvPdBU2d
5G2Q==
X-Gm-Message-State: AOAM533sgqtoaa1CqzZg53v1Hz1/EAyhciQ4VBHYwSJVEL2+hovtQEOS
iRQtFJwBG4QKZCf+9zVeqtnXWQ==
X-Google-Smtp-Source: ABdhPJwzi7HMJtmeFn67azg1yvco5LgQ1BnQsIpJ8IJ5xT1mpOosVRpB4EqupaGOZXPtQpt3m4F9ow==
X-Received: by 2002:ac2:4bc1:: with SMTP id o1mr1813194lfq.666.1640265749131;
Thu, 23 Dec 2021 05:22:29 -0800 (PST)
Received: from localhost (109-252-167-227.dynamic.spd-mgts.ru.
[109.252.167.227])
by smtp.gmail.com with ESMTPSA id 6sm505052ljs.39.2021.12.23.05.22.27
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Thu, 23 Dec 2021 05:22:28 -0800 (PST)
From: Andrew Tropin <andrew@HIDDEN>
To: guix-devel@HIDDEN, guix-patches@HIDDEN, Ludovic =?utf-8?Q?Court?=
=?utf-8?Q?=C3=A8s?= <ludo@HIDDEN>
Subject: [PATCH v2] doc: Add Writing Service Configuration section.
In-Reply-To: <87h7b2b6n3.fsf@HIDDEN>
Date: Thu, 23 Dec 2021 16:22:25 +0300
Message-ID: <87czln5ucu.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: multipart/signed; boundary="=-=-=";
micalg=pgp-sha512; protocol="application/pgp-signature"
X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::134
(failed)
Received-SPF: none client-ip=2a00:1450:4864:20::134;
envelope-from=andrew@HIDDEN; helo=mail-lf1-x134.google.com
X-Spam_score_int: -10
X-Spam_score: -1.1
X-Spam_bar: -
X-Spam_report: (-1.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RDNS_NONE=0.793,
SPF_HELO_NONE=0.001, SPF_NONE=0.001 autolearn=no autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: submit
Cc: Xinglu Chen <public@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)
--=-=-=
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
* guix.texi (Writing Service Configuration): New section.
=2D--
doc/guix.texi | 252 +++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 248 insertions(+), 4 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index 333cb4117a..29d85d3dc5 100644
=2D-- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -10363,6 +10363,7 @@ compiling modules. It can be @code{#f}, @code{#t},=
or @code{'detailed}.
The other arguments are as for @code{derivation} (@pxref{Derivations}).
@end deffn
=20
+@anchor{file-like objects}
@cindex file-like objects
The @code{local-file}, @code{plain-file}, @code{computed-file},
@code{program-file}, and @code{scheme-file} procedures below return
@@ -15942,6 +15943,7 @@ symlink:
Return a service that sets the host name to @var{name}.
@end deffn
=20
+@anchor{console-font-service-type}
@defvr {Scheme Variable} console-font-service-type
Install the given fonts on the specified ttys (fonts are per
virtual console on the kernel Linux). The value of this service is a list=
of
@@ -33717,6 +33719,7 @@ a daemon that can execute application bundles (some=
times referred to as
=20
@end defvr
=20
+@anchor{docker-configuration}
@deftp {Data Type} docker-configuration
This is the data type representing the configuration of Docker and Contain=
erd.
=20
@@ -35652,10 +35655,11 @@ them in an @code{operating-system} declaration. =
But how do we define
them in the first place? And what is a service anyway?
=20
@menu
=2D* Service Composition:: The model for composing services.
=2D* Service Types and Services:: Types and services.
=2D* Service Reference:: API reference.
=2D* Shepherd Services:: A particular type of service.
+* Service Composition:: The model for composing services.
+* Service Types and Services:: Types and services.
+* Writing Service Configurations:: A guideline for writing guix services.
+* Service Reference:: API reference.
+* Shepherd Services:: A particular type of service.
@end menu
=20
@node Service Composition
@@ -35851,6 +35855,245 @@ There can be only one instance of an extensible s=
ervice type such as
Still here? The next section provides a reference of the programming
interface for services.
=20
+@node Writing Service Configurations
+@subsection Writing Service Configurations
+
+Guix already contains a wide variety of system and home services, but
+sometimes users might want to add new services. This section contains
+tips for simplifying this process, and should help to make service
+configurations and their implementations more consistent.
+
+@quotation Note
+If you find any exceptions or patterns missing in this section, please
+send a patch with additions/changes to @email{guix-devel@@gnu.org}
+mailing list or just start a discussion/ask a question.
+@end quotation
+
+@subsubheading Configuration Itself
+
+As we know from previous sections, a Guix service can accept a service
+value, usually some kind of configuration record and optionally, be
+extended with additional values by other services (@pxref{Service
+Composition}).
+
+When being extended, most services take some kind of configuration
+record or a list thereof, but in some cases a simpler value is all
+that is necessary.
+
+There are some cases, when the service accepts a list of pairs or some
+other non-record values. For example, @code{console-font-service-type}
+(@pxref{console-font-service-type}) accepts an
+association list, and @code{etc-service-type} (@pxref{etc-service-type})
+accepts a list of lists. Those services are kinda special, they do
+auxiliary work of setting up some part of the operating system or home
+environment, or just an intermediate helpers used by other Guix
+services. For example @code{etc-service-type} is not that useful on its
+own, but it helps other services to create files in /etc directory, when
+it necessary.
+
+However, in most cases a Guix service is wrapping some software, which
+consists of one or more packages, and configuration file or files.
+Therefore, the value for such service is quite complicated and it's hard
+to represent it with just a list or basic data type, in such cases we
+use a record. Each such record (@pxref{SRFI-9 Records, Scheme Records,,
+guile, GNU Guile Reference Manual}) have @samp{-configuration} suffix,
+for example, the @code{docker-service-type} should accept a record type
+named @code{docker-configuration}, which contains fields used to
+configure Docker. Configuration records for home services should also
+have a @code{home-} prefix in their name.
+
+There is a module @code{gnu service configuration}, which contains
+helpers simplifying configuration definition process. Take a look at
+@code{gnu services docker} module or grep for
+@code{define-configuration} to find usage examples.
+
+@c Provide some examples, tips, and rationale behind @code{gnu service
+@c configuration} module.
+
+After a configuration record has been properly named and defined let's
+discuss how to name and define the fields, and which approach to use for
+implementing the serialization code related to them.
+
+In this context, the @dfn{serialization} is a process of converting
+values of the fields defined in service configuration into a string or
+strings of a target config format, which will be put to the
+configuration file or files used by the program.
+
+@subsubheading Configuration Record Fields
+
+@enumerate
+@item
+It's a good idea to have one or more fields for specifying the package
+or packages that will be installed by a service. For example,
+@code{docker-configuration} has @code{docker}, @code{docker-cli},
+@code{containerd} fields (@pxref{docker-configuration}). Sometimes it
+make sense to make a field, which accepts a list of packages for cases,
+where an arbitrary list of plugins can be passed to the configuration.
+There are some services, which provide a field called @code{package} in
+their configuration, which is ok, but the way it done in
+@code{docker-configuration} is more flexible and thus preferable.
+
+@item
+Fields for configuration files, should be name the same as target
+configuration file name, but in kebab-case@footnote{The case used for
+identifiers in languages of Lisp family, example:
+@code{this-is-kebab-case}.}: @code{bashrc} for @file{.bashrc},
+@code{bash-profile} for @file{.bash_profile},
+@code{tmux-conf} for @file{tmux.conf}, etc. The implementation
+for such fields will be discussed in the next subsubsection.
+
+@item
+Other fields in most cases add some boilerplates/reasonable defaults to
+configuration files, enable/disable installation of some packages or
+provide other custom behavior, for example @code{guix-defaults?} or
+@code{aliases} fields in @code{home-bash-configuration}
+(@pxref{home-bash-configuration}). There is no any special requirements
+or recommendations here, but it's necessary to make it possible to
+disable all the effects of such fields to provide a user with an empty
+configuration and let them generate it from scratch with only field for
+configuration file. For example, setting @code{guix-defaults?} to
+@code{#f} and @code{aliases} to @code{'()} will give user an ability to
+control the content of @file{.bashrc} solely by setting the value of
+@code{bashrc} field.
+
+
+@end enumerate
+
+@subsubheading Fields for Configuration Files
+
+The field should accept a data structure (preferably a combination of
+simple lists, alists, @ref{Vectors, vectors,, guile,},
+@ref{G-Expressions, gexps} and basic data types), which will be
+serialized to target configuration format, in other words, it should
+provide an alternative Lisp syntax, which can be later translated to a
+target one, like SXML to XML. Such approach is quite flexible and
+simple, it requires to write serializer once for one configuration
+format and can be reused multiple times in different Guix services.
+
+Let's take a look at JSON: we implement serialization function, which
+converts vectors to arrays, alists to objects (AKA dictionaries or
+associative arrays), numbers to numbers, gexps to the strings,
+@ref{file-like objects} (@pxref{G-Expressions}) to the strings, which
+contains the path to the file in the store, @code{#t} to @code{true} and
+so on, and now we have all programs using JSON as a format for
+configurations covered. Maybe some fine-tunning will be needed for
+particular application, but the primary serialization part is already
+finished.
+
+The pros and cons of such approach is inherited from open-world
+assumption. It doesn't matter if the underlying applications provides
+new configuration options, we don't need to change anything in the
+service configuration and its serialization code, it will work perfectly
+fine. On the other hand, it is harder to type check and structure check
+at ``compile-time'', and we can end up with a configuration, which won't
+be accepted by the target program due to unexisting, misspelled or
+wrongly-typed options. It's possible to add those checks, but we will
+get the drawbacks of closed-world assumption: we need to keep the
+service implementation in-sync with app config options, and it will make
+impossible to use the same service with older/newer package version,
+which has a slightly different list of available options and will add an
+excessive maintanence load.
+
+However, for some applications with really stable configuration those
+checks can be helpful and should be implemented if possible, for some
+others we can implement them only partially.
+
+The alternative approach applied in some exitsting services is to use
+records for defining the structure of configuration field, it has the
+same downsides of closed-world assumption and a few more problems:
+
+@enumerate
+@item
+It has to replicate all the available options for the app (sometimes
+hundreds or thousands) to allow the user express any configuration they
+want.
+@item
+Having a few records adds one more layer of abstraction between service
+configuration and resulting app config, including different field
+casing, new semantic units.
+@c provide examples?
+@item
+It harder to implement optional settings, serialization becomes very
+ad-hoc and hard to reuse among other services with the same target
+config format.
+@end enumerate
+
+Exceptions can exist, but the overall idea is to provide a lispy syntax
+for target configuration. Take a look at Sway example configuration
+(which also can be used for i3). The following value of @code{config}
+field of @code{home-sway-configuration}:
+
+@example
+`((include ,(local-file "./sway/config"))
+ (bindsym $mod+Ctrl+Shift+a exec emacsclient -c --eval "'(eshell)'")
+ (bindsym $mod+Ctrl+Shift+o "[class=3D\"IceCat\"]" kill)
+ (input * ((xkb_layout us,ru)
+ (xkb_variant dvorak,))))
+@end example
+
+would yield something like:
+
+@example
+include /gnu/store/408jwvh6wxxn1j85lj95fniih05gx5xj-config
+bindsym $mod+Ctrl+Shift+a exec emacsclient -c --eval '(eshell)'
+bindsym $mod+Ctrl+Shift+o [class=3D"IceCat"] kill
+input * @{
+ xkb_layout us,ru
+ xkb_variant dvorak,
+@}
+@end example
+
+The mapping between Scheme code and resulting configuration is quite
+obvious. The serialization code with some type and structure checks
+takes less than 70 lines and every possible Sway/i3 configuration can be
+expressed using this field.
+
+@subsubheading Let User Escape
+Sometimes a user already has a configuration file for an program, make
+sure that it is possible to reuse it directly without rewriting. In the
+example above, the following snippet allows one to include already an
+existing config to the newly generated one utilizing @code{include}
+directive of i3/Sway config language:
+
+@lisp
+(include ,(local-file "./sway/config"))
+@end lisp
+
+When building a resulting config the file-like objects are substituted
+with a path of the file in the store and Sway's @code{include} loads
+this file during startup. The way file-like objects are treated here
+also allows one to specify paths to plugins or other binary files like:
+
+@lisp
+(load-plugin ,(file-append plugin-package "/share/plugin.so"))
+@end lisp
+
+(the example value for imaginary service configuration config file
+field).
+
+In some cases the target configuration language may not have such an
+@code{include} directive and can't provide such a functionallity, to
+workaround it we can do the following trick:
+
+@lisp
+#~(call-with-input-file
+ #$(local-file "./sway/config")
+ (@@ (ice-9 textual-ports) get-string-all))
+@end lisp
+
+The =E2=80=98get-string-all=E2=80=99 procedure will read the contents of t=
he
+@file{./sway/config} file (to be more preciese the copy of this file
+placed in the store), and return a string containing the contents. Once
+serialized, the G-expression will thus be turn into the contents of the
+Sway configuration file in @file{./sway/config}. This code can be
+easily combined with the rest of Sway's configuration, additionally, we
+can control the place where the content of @file{./sway/config} will
+appear in resulting file by moving this snippet around.
+
+Following these simple rules will help to make simple, consistent and
+maintainable service configurations, and will let users express any
+possible needs and reuse existing configuration files.
+
@node Service Reference
@subsection Service Reference
=20
@@ -36076,6 +36319,7 @@ The type of the ``boot service'', which produces th=
e @dfn{boot script}.
The boot script is what the initial RAM disk runs when booting.
@end defvr
=20
+@anchor{etc-service-type}
@defvr {Scheme Variable} etc-service-type
The type of the @file{/etc} service. This service is used to create
files under @file{/etc} and can be extended by
=2D-=20
2.34.0
--=-=-=
Content-Type: application/pgp-signature; name="signature.asc"
-----BEGIN PGP SIGNATURE-----
iQJDBAEBCgAtFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmHEeBEPHGFuZHJld0B0
cm9wLmluAAoJECII0glYwd6wZYMQAIvoi0tVHwWUFhfmI75JUb483zA1fVDa6pI9
4/XHuE1XdGEdC4Wbjvfnh14ue1rJMF/lMuY6PnRRXHT4kniON+poGYPD0S4W02V+
cFISWTuSTwFnRaZjs9y4qet1S2a0JVBv5CBH1BtK1nK+MB2l0Djsj388Nlxc5uUI
YGueNBxFB5eBweOn8sTOGROyy/8ZV3kGzIuHyE7X8aY9pV31/30tzYY6KqELwx5K
I4mnEmSftq/OF55xu0R3SPazUN9W3F7/GIbmy6BPpd0495VTu4IGXdS3Gpyf40L7
tXFl/8pC3BYPOgcSUmSw7/eyruKtVxwOFm0t/4GmlwtVIKUBFPHavP5S3nj9K7l9
I8OnZjWMlAcPqr/VS7YCcuimwUEuhr5CLThGJPPcL4bFuRwHZez+n2nQyD8Vt1NM
qUQavA1y/vv3DACtGmqUc/ZAm4H/5gXa8ka/gx25nqaM/2h+uRnq074FI4Xja8iD
iX0dezQp7SAbIWT3ANkw339laQTFebhkAstrpgOWn7kXtMmY0Sip1p1DXhk0ipzb
9MK+2FiKfSOW6S9Oevfz/k8JsvByUTnHa8BIj4yx4yNS82U3LmW2XVsVAniYxnSK
mUYdpnCfJJZnv3XBK+o0MTGa2qoRzv3h2XjhLAAoVefENdaBnBbppvsSBFYVdFp4
fjDkZbGj
=2leU
-----END PGP SIGNATURE-----
--=-=-=--
guix-patches@HIDDEN:bug#52698; Package guix-patches.
Full text available.
Received: (at submit) by debbugs.gnu.org; 22 Dec 2021 08:53:39 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed Dec 22 03:53:39 2021
Received: from localhost ([127.0.0.1]:56762 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1mzxNS-0004yO-CC
for submit <at> debbugs.gnu.org; Wed, 22 Dec 2021 03:53:39 -0500
Received: from lists.gnu.org ([209.51.188.17]:47866)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <public@HIDDEN>) id 1mzxNR-0004yH-2J
for submit <at> debbugs.gnu.org; Wed, 22 Dec 2021 03:53:38 -0500
Received: from eggs.gnu.org ([209.51.188.92]:36008)
by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <public@HIDDEN>)
id 1mzxNQ-00080Z-Ih; Wed, 22 Dec 2021 03:53:36 -0500
Received: from h87-96-130-155.cust.a3fiber.se ([87.96.130.155]:41560
helo=mail.yoctocell.xyz)
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <public@HIDDEN>)
id 1mzxNL-0007h2-Kn; Wed, 22 Dec 2021 03:53:36 -0500
From: Xinglu Chen <public@HIDDEN>
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yoctocell.xyz;
s=mail; t=1640163203;
bh=wtPe4iSxxm804VqkZDqGiYyAvIuHP0ZS/Oz+T8WIAfs=;
h=From:To:Subject:In-Reply-To:Date;
b=Qwy5G9GUDv0KszedGlgL1dZut7cNFNHj1wpr0I1fqlishKRd0LBkukIiyBAKOug1A
24tfT82JyTOyiCV1VvuEikUDcCygqrEl5w0fS7tZCa99RYeccr3Mh5cYI7mjruY5+r
X6QGlheQB6vkzW2PvHDO1SB4KubarK0LAbE+whNs=
To: Andrew Tropin <andrew@HIDDEN>, guix-devel@HIDDEN,
guix-patches@HIDDEN, Ludovic =?utf-8?Q?Court=C3=A8s?= <ludo@HIDDEN>
Subject: Re: [RFC PATCH] doc: Add Writing Service Configuration section.
In-Reply-To: <87h7b2b6n3.fsf@HIDDEN>
Date: Wed, 22 Dec 2021 09:53:22 +0100
Message-ID: <87k0fxvx4t.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: multipart/signed; boundary="=-=-=";
micalg=pgp-sha256; protocol="application/pgp-signature"
Received-SPF: pass client-ip=87.96.130.155; envelope-from=public@HIDDEN;
helo=mail.yoctocell.xyz
X-Spam_score_int: 14
X-Spam_score: 1.4
X-Spam_bar: +
X-Spam_report: (1.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1,
DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FROM_SUSPICIOUS_NTLD=0.499,
PDS_OTHER_BAD_TLD=1.999, PDS_RDNS_DYNAMIC_FP=0.01, RDNS_DYNAMIC=0.982,
SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no
X-Spam_action: no action
X-Spam-Score: 1.1 (+)
X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org",
has NOT identified this incoming email as spam. The original
message has been attached to this so you can view it or label
similar future email. If you have any questions, see
the administrator of that system for details.
Content preview: Am Dienstag, der 21. Dezember 2021, um 13:21 +032, schrieb
Andrew Tropin <andrew@HIDDEN>: > * guix.texi (Writing Service Configuration):
New section. > --- > After reading the source code of different system
services
and implementing a > few of home services I decided to write down most im
[...] Content analysis details: (1.1 points, 10.0 required)
pts rule name description
---- ---------------------- --------------------------------------------------
2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs
[URI: yoctocell.xyz (xyz)]
1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail)
-0.0 SPF_HELO_PASS SPF: HELO matches SPF record
-2.3 RCVD_IN_DNSWL_MED RBL: Sender listed at https://www.dnswl.org/,
medium trust [209.51.188.17 listed in list.dnswl.org]
-0.0 RCVD_IN_MSPIKE_H3 RBL: Good reputation (+3)
[209.51.188.17 listed in wl.mailspike.net]
0.5 FROM_SUSPICIOUS_NTLD From abused NTLD
-0.0 RCVD_IN_MSPIKE_WL Mailspike good senders
X-Debbugs-Envelope-To: submit
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: 1.1 (+)
X-Spam-Report: Spam detection software, running on the system "debbugs.gnu.org",
has NOT identified this incoming email as spam. The original
message has been attached to this so you can view it or label
similar future email. If you have any questions, see
the administrator of that system for details.
Content preview: Am Dienstag, der 21. Dezember 2021, um 13:21 +032, schrieb
Andrew Tropin <andrew@HIDDEN>: > * guix.texi (Writing Service Configuration):
New section. > --- > After reading the source code of different system services
and implementing a > few of home services I decided to write down most im
[...]
Content analysis details: (1.1 points, 10.0 required)
pts rule name description
---- ---------------------- --------------------------------------------------
-0.0 RCVD_IN_MSPIKE_H3 RBL: Good reputation (+3)
[209.51.188.17 listed in wl.mailspike.net]
-2.3 RCVD_IN_DNSWL_MED RBL: Sender listed at https://www.dnswl.org/,
medium trust
[209.51.188.17 listed in list.dnswl.org]
2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs
[URI: yoctocell.xyz (xyz)]
1.0 SPF_SOFTFAIL SPF: sender does not match SPF record (softfail)
-0.0 SPF_HELO_PASS SPF: HELO matches SPF record
0.5 FROM_SUSPICIOUS_NTLD From abused NTLD
-0.0 RCVD_IN_MSPIKE_WL Mailspike good senders
1.0 BULK_RE_SUSP_NTLD Precedence bulk and RE: from a suspicious TLD
-1.0 MAILING_LIST_MULTI Multiple indicators imply a widely-seen list
manager
--=-=-=
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Am Dienstag, der 21. Dezember 2021, um 13:21 +032, schrieb Andrew Tropin <a=
ndrew@HIDDEN>:
> * guix.texi (Writing Service Configuration): New section.
> ---
> After reading the source code of different system services and implementi=
ng a
> few of home services I decided to write down most important tips for
> implementing guix service configurations. I belive having such a guideli=
ne
> can simplify the development of new services and configurations for them,=
as
> well as keeping those implementations consistent, which will simplify the=
life
> for users too because they won't need to learn a different configuration
> approaches for different services.
>
> This section is not a final document, but a starting point for discussion=
and
> further extension of the guideline. Feel free to raise a question, point=
to a
> mistake, make a suggestion or propose an idea.
Thanks for working on this! I left some comments and thoughts as I read
through it (Warning, these is quite a lot :-)).
> doc/guix.texi | 209 +++++++++++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 205 insertions(+), 4 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 333cb4117a..a48fb0e2b7 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -35652,10 +35652,11 @@ them in an @code{operating-system} declaration.=
But how do we define
> them in the first place? And what is a service anyway?
>=20=20
> @menu
> -* Service Composition:: The model for composing services.
> -* Service Types and Services:: Types and services.
> -* Service Reference:: API reference.
> -* Shepherd Services:: A particular type of service.
> +* Service Composition:: The model for composing services.
> +* Service Types and Services:: Types and services.
> +* Service Reference:: API reference.
> +* Shepherd Services:: A particular type of service.
> +* Writing Service Configurations:: A guideline for writing guix services.
> @end menu
>=20=20
> @node Service Composition
> @@ -35851,6 +35852,206 @@ There can be only one instance of an extensible=
service type such as
> Still here? The next section provides a reference of the programming
> interface for services.
>=20=20
> +@node Writing Service Configurations
> +@subsection Writing Service Configurations
The TOC menu says that =E2=80=9CWriting Services Configurations=E2=80=9D co=
mes after
=E2=80=9CShepherd Services=E2=80=9D, but this doesn=E2=80=99t seem to be th=
e case here.
> +There are a lot of system and home services already written, but from
> +time to time it's necessary to write one more.
I would write something like
Guix already contains a wide variety of system and home services, but
sometimes users might want to add new services.
> +This section contains
> +tips for simplifying this process, and should help to make service
> +configurations and their implementations more consistent.
> +
> +@quotation Note
> +If you find any exceptions or patterns missing in this section, please
> +send a patch with additions/changes to @email{guix-devel@@gnu.org}
> +mailing list or just start a discussion/ask a question.
> +@end quotation
I don=E2=80=99t think this note is really necessary; there is already a sec=
tion
on contributing to the project, see =E2=80=9C17 Contributing=E2=80=9D.
> +@subsubheading Configuration Itself
> +
> +As we know from previous section a guix service can accept a value and
^ missing comma
s/section/sections/
s/guix/Guix
When you say =E2=80=9Cservice=E2=80=9D, you mean a =E2=80=9Cservice type=E2=
=80=9D, right? Just =E2=80=9Cvalue=E2=80=9D
sounds a bit vague, maybe
=E2=80=A6 a value, usually some kind of configuration
record (@pxref{RELEVANT NODE(s)})
?
> +be extended with additional values by other services.
Not all services are extendable though, to avoid ambiguity, maybe
=E2=80=A6, and optionally, be extended with additional configurations by =
other
services (@pxref{Service Composition}).
> +There are some
> +cases, when the service accepts a list of pairs or some other values for
I suggest:
When being extended, most services take some kind of configuration
record or a list thereof, but in some cases a simpler value is all
that is necessary.
> +example @code{console-font-service-type} accepts list of pairs (tty and
> +font name/file) or @code{etc-service-type} accepts list of lists
> +(resulting file name and file-like object)
It is probably better to link to the service documentation instead of
trying to explain the specification in a few words in brackets. You can
use Texinfo =E2=80=9Canchors=E2=80=9D to achieve this, see =E2=80=9C5.8 '@a=
nchor': Defining
Arbitrary Cross-reference Targets=E2=80=9D.
For example, @code{console-font-service-type}
(@pxref{console-font-service-type}) accepts an association list, and
@code{etc-service-type} (@pxref{etc-service-type}) accepts a list of
lists.
Also, is should there be any preference for using alists or list of
lists or vice versa?
> +those services are kinda special, they are an intermediate helpers
> +doing auxiliary work.
It is not clear what the last clause means, how do they differ from
other, more =E2=80=9Cregular=E2=80=9D services?
> +However, in most cases a guix service is wrapping some software, which
> +consist of package or a few packages, and configuration file or files.
=E2=80=9C=E2=80=A6consists of one or more packages and configuration files.=
=E2=80=9D
> +Therefore, the value for such service is quite complicated and it's hard
> +to represent it with a just list or basic data type, in such cases we
> +use a record. Each such record have -configuration suffix, for example
^^ Link to the =E2=80=9CRecords=E2=80=9D page in the Guile m=
anual
@code{-configuration} or maybe @samp{-configuration}
> +@code{docker-configuration} for @code{docker-service-type} and a few
> +different fields helping to customize the software.
I suggest:
=E2=80=A6, for example, the @code{docker-service-type} should accept a re=
cord
type named @code{docker-configuration}, which contains a fields used
to configure Docker.
> +Configuration
> +records for home services also have a @code{home-} prefix in their name.
^ missing =E2=80=9Cshould=E2=80=9D
> +There is a module @code{gnu service configuration}, which contains
> +helpers simplifying configuration definition process. Take a look at
> +@code{gnu services docker} module or grep for
> +@code{define-configuration} to find usage examples.
> +
> +@c Provide some examples, tips, and rationale behind @code{gnu service
> +@c configuration} module.
Note that I already sent a patch that (at least tries to) document (gnu
service configuration)[1].
One thing that is lacking is when to use (guix records) (which isn=E2=80=99t
documented yet) vs (gnu service configuration). There should probably
be one or two paragraphs about that.
> +After a configuration record properly named and defined let's discuss
^ =E2=80=9C=E2=80=A6has been=E2=80=A6=E2=80=
=9D
> +how to name and define fields, and which approach to use for
^ missing =E2=80=9Cthe=E2=80=9D
> +implementing the serialization code related to them.
=E2=80=9Cserialization=E2=80=9D doesn=E2=80=99t seem to be mentioned anywhe=
re else in the manual
in the context of Guix services, so I think we should avoid using that
term before explaining what it actually means. Maybe
=E2=80=A6and what approach to use to convert Scheme records into strings,=
which
will be put into one or more configuration files.
> +@subsubheading Configuration Record Fields
> +
> +@enumerate
> +@item
> +It's a good idea to have a field/fields for specifying package/packages
> +being installed for this service. For example
^ missing comma
I suggest
It's a good idea to have one or more fields for specifying the package
or packages that will be installed by a service.=20
> +@code{docker-configuration} has @code{docker}, @code{docker-cli},
> +@code{containerd} fields.
Having a link to the docker service would probably be a good idea.
> +Sometimes it make sense to make a field,
> +which accepts a list of packages for cases, where an arbitrary list of
> +plugins can be passed to the configuration. There are some services,
> +which provide a field called @code{package} in their configuration,
> +which is ok, but the way it done in @code{docker-configuration} is more
> +flexible and thus preferable.
In what way is it more flexible? Just naming the field =E2=80=98docker=E2=
=80=99 would
be a bit ambigous; =E2=80=98docker-package=E2=80=99 make things more clear.
> +@item
> +Fields for configuration files, should be called the same as target
s/called/named/
=E2=80=9C=E2=80=A6same as the name of the target configuration file=E2=80=9D
> +configuration file name, but in kebab-case: bashrc for bashrc,
Not everyone might familiar with what exactly =E2=80=9Ckebab-case=E2=80=9D =
means; we
should probably leave a footnote or something.
=E2=80=9C=E2=80=A6@code{bashrc} for @file{.bashrc}=E2=80=A6=E2=80=9D
It should also mention that preceding dots should be removed as well.
What should happend with files named =E2=80=98file.ext=E2=80=99? Should th=
e field be
named =E2=80=98file-ext=E2=80=99?
> +bash-profile for bash_profile, etc. The implementation for such fields
=E2=80=9C=E2=80=A6@code{bash-profile} for @file{.bash_profile}.
Also, many services have an =E2=80=98extra-content=E2=80=99, =E2=80=98extra=
-config=E2=80=99, or
=E2=80=98extra-options=E2=80=99 field. In most cases these just take a str=
ing and
appends it to some configuration file. Should these instead be named
=E2=80=98sshd_config=E2=80=99, =E2=80=98xserver-conf=E2=80=99, and =E2=80=
=98asound-config=E2=80=99, respectively?
> +@item
> +Other fields in most cases add some boilerplates/reasonable defaults to
^ missing =E2=80=9Cshould=E2=80=9D maybe?
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20
> +configuration files
Do you mean that for some services, there could be a
=E2=80=98reasonable-defaults?=E2=80=99 field that sets some resonable defau=
lts?
> +turns on/off installation of some packages or provide other custom
> behavior.
=E2=80=9Cturns on/off=E2=80=9D sounds a bit weird; I think =E2=80=9Cenable/=
disabled=E2=80=9D sounds
better.
> +There is no any special requirements or
> +recommendations here, but it's necessary to make it possible to disable
> +all the effects of such fields to provide a user with an empty
> +configuration and let them generate it from scratch with only field for
> +configuration file.
I don=E2=80=99t really understand what is meant by =E2=80=9Clet them genera=
te it from
scratch with only field for configuration file=E2=80=9D.=20=20
It doesn=E2=80=99t mention if a configuration record should cover all the
configuration options available in a configuration file. For example,
the current =E2=80=98openssh-configuration=E2=80=99 has quite a few options=
, but these
obviously don=E2=80=99t cover all the options available in /etc/ssh/sshd_co=
nfig,
which is why there is an =E2=80=9Cescape hatch=E2=80=9D, =E2=80=98extra-con=
tent=E2=80=99 field.
In some cases a program might have too many configuration fields for us
to map using configuration records, e.g., Git. In rde, the approach we
took was to use nested lists to represent the INI configuration. I
think this approach could also be mentioned here.
> +@end enumerate
> +
> +@subsubheading Fields for Configuration Files
> +
> +The field should accept a datastructure (preferably a combination of
^ missing space
> +simple lists, alists, vectors, gexps and basic data types), which will
There should probably be links to at least =E2=80=98vectors=E2=80=99 and =
=E2=80=98gexps=E2=80=99, since
many people probably aren=E2=80=99t too familiar with them.
> +be serialized to target configuration format, in other words it should
missing comma ^=20
> +provide an alternative lisp syntax, which can be later translated to
Capitalize =E2=80=9Clisp=E2=80=9D.
> +target one, like SXML for XML. Such approach is quite flexible and
^ missing =E2=80=9Ca=E2=80=9D
You mean =E2=80=9CSXML to XML=E2=80=9D, right (SXML being the Lisp syntax, =
and XML being
the target one)?
> +simple, it requires to write serializer once for one configuration
^ =E2=80=9Cone=E2=80=9D or =E2=80=9Cyou=E2=80=9D
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20
> +format and can be reused multiple times in different guix services.
Capitalize =E2=80=9Cguix=E2=80=9D.
> +Let's take a look at JSON: we implement serialization function, which
> +converts vectors to arrays, alists to objects (AKA dictionaries or
> +associative arrays), numbers to numbers, gexps to the strings, file-like
> +objects to the strings, which contains the path to the file in the
> +store, @code{#t} to @code{true} and so on, and now we have all apps
=E2=80=9CApps=E2=80=9D sounds kind of smartphone-y; =E2=80=9Cprograms=E2=80=
=9D is probably more
appropriate.
There should be a link =E2=80=9Cfile-like object=E2=80=9D since it may be u=
nknown for
many.
> +using JSON and YAML as a format for configurations covered. Maybe some
You only mentioned JSON above; why would YAML also be covered by JSON?
> +fine-tunning will be needed for particular application, but the primary
> +serilalization part is already finished.
=E2=80=9Cserialization=E2=80=9D typo.
> +The pros and cons of such approach is inherited from open-world
> +assumption. It doesn't matter if underlying applications provides new
^ =E2=80=9Cthe=E2=80=9D
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20=20=20=20=20=20=20
What do you mean by =E2=80=9Copen-world assumption=E2=80=9D?
> +configuration options, we don't need to change anything in service
^ =E2=80=9Cthe=
=E2=80=9D
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20=20=20=20=20=20=20
> +configuration and its serialization code, it will work perfectly fine,
A full stop should probably be used here ^
> +on the other hand it harder to type check and structure check
^ =E2=80=9Cis=E2=80=9D
> +``compile-time'', and we can end up with configuration, which won't be
^ missing =E2=80=9Cduring=E2=80=9D or =E2=80=9Cat=E2=80=9D? =
^ =E2=80=9Ca=E2=80=9D
=20=20=20
> +accepted by target application cause of unexisting, misspelled or
^ =E2=80=9Cthe=E2=80=9D
s/application/program/ :-)
s/cause/because/
> +wrongly-typed options. It's possible to add those checks, but we will
> +get the drawbacks of closed-world assumption: we need to keep the
> +service implementation in-sync with app config options, and it will make
> +impossible to use the same service with older/newer package version,
> +which has a slightly different list of available options and will add an
> +excessive maintanence load.
> +
> +However, for some applications with really stable configuration those
> +checks can be helpful and should be implemented if possible, for some
> +other we can implement them only partially.
s/other/others/
> +The alternative approach applied in some exitsting services is to use
> +records for defining the structure of configuration field, it has the
> +same downsides of closed-world assumption and a few more problems:
> +
> +@enumerate
> +@item
> +It has to replicate all the available options for the app (sometimes
> +hundreds or thousands) to allow user express any configuration they
^ =E2=80=9Cthe=E2=80=9D
> +wants.
s/wants/want/
> +@item
> +Having a few records, adds one more layer of abstraction between service
^ spurious comma
> +configuration and resulting app config, including different field
> +casing, new semantic units.
But it means that the syntax for configuring a program is more
Scheme-like. For example, the Dovecot service provides a very
complicated but Schemeish interface for configuring Dovecot, though as
you have mentioned, it might be missing some fields since the Dovecot
configuration file might have changed since the creation of the service.
> +@c provide examples?
> +@item
> +It harder to implement optional settings, serialization becomes very
> +ad-hoc and hard to reuse among other services with the same target
> +config format.
> +@end enumerate
> +
> +Exceptions can exist, but the overall idea is to provide a lispy syntax
> +for target configuration. Take a look at sway example configuration
Capitalize =E2=80=9CSway=E2=80=9D.
> +(which also can be used for i3). The following value of @code{config}
> +field of @code{home-sway-configuration}:
=E2=80=98home-sway-configuration=E2=80=99 isn=E2=80=99t in Guix as of now, =
so it probably
shouldn=E2=80=99t be mentioned, as least for now.
> +@example
> +`((include ,(local-file "./sway/config"))
> + (bindsym $mod+Ctrl+Shift+a exec emacsclient -c --eval "'(eshell)'")
> + (bindsym $mod+Ctrl+Shift+o "[class=3D\"IceCat\"]" kill)
> + (input * ((xkb_layout us,ru)
> + (xkb_variant dvorak,))))
> +@end example
> +
> +would yield something like:
> +
> +@example
> +include /gnu/store/408jwvh6wxxn1j85lj95fniih05gx5xj-config
> +bindsym $mod+Ctrl+Shift+a exec emacsclient -c --eval '(eshell)'
> +bindsym $mod+Ctrl+Shift+o [class=3D"IceCat"] kill
> +input * @{
> + xkb_layout us,ru
> + xkb_variant dvorak,
> +@}
> +@end example
> +
> +The mapping between scheme code and resulting configuration is quite
Capitalize =E2=80=9CScheme=E2=80=9D.
> +obvious. The serialization code with some type and structure checks
> +takes less than 70 lines and every possible sway/i3 configuration can be
Not sure if LoC is the best measure, and since =E2=80=98home-sway-configura=
tion=E2=80=99
isn=E2=80=99t in Guix proper, users have no idea of where to look if they w=
ant
to see the source code.
> +expressed using this field.
> +
> +@subsubheading Let User Escape
I suggest =E2=80=9CEscape Hatches=E2=80=9D since the term is already mentio=
ned in some
places in the manual.
> +Sometimes user already have a configuration file for an app, make sure
^ =E2=80=9Ca=E2=80=9D
s/have/has/
s/app/program/
> +that it is possible to reuse it directly without rewriting. In the
> +example above, the following snippet allows to include already existing
missing =E2=80=9Cyou=E2=80=9D or =E2=80=9Cone=E2=80=
=9D ^ ^ missing =E2=80=9Can=E2=80=9D
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20
> +config to the newly generated one utilizing @code{include} directive of
> +i3/sway config language:
> +
> +@example
> +(include ,(local-file "./sway/config"))
> +@end example
Use @lisp instead.
> +When building a resulting config the file-like objects are substituted
> +with a path of the file in the store and sway's @code{include} loads
> +this file during startup. The way file-like objects are treated here
> +also allows to specify paths to plugins or other binary files like:
^ missing =E2=80=9Cyou=E2=80=9D or =E2=80=9Cone=E2=80=9D
=20=20=20=20=20=20=20
> +@code{(load-plugin ,(file-append plugin-package "/share/plugin.so"))}
This should probably be put in its own @lisp block.
> +(the example value for imaginary service configuration config file
> +field).
> +
> +In some cases target configuration language may not have such
^ =E2=80=9Cthe=E2=80=9D missing =
=E2=80=9Can=E2=80=9D ^
> +@code{include} directive and can't provide such a functionallity, to
> +workaround it we can do the following trick:
> +
> +@example
> +`(#~(call-with-input-file
> + #$(local-file "./sway/config")
> + (@@ (ice-9 textual-ports) get-string-all)))
> +@end example
Use @lisp instead.
Where exactly should something like this be put?
=E2=80=98@@=E2=80=99 is not a good practice; better to use =E2=80=98use-mod=
ules=E2=80=99 at the
beginning of the file.
> +G-expressions get serialized to its values, and the example above reads
> +the content of the file-like object and inserts it in the resulting
> +configuration file.
I suggest
The =E2=80=98get-string-all=E2=80=99 procedure will read the contents of =
the
@file{./sway/config} file, and return a string containing the
contents. Once serialized, the G-expression will thus be turn into
the contents of the Sway configuration file in @file{./sway/config}.
> +Following these simple rules will help to make a simple, consistent and
^ spurious =E2=80=9Ca=E2=
=80=9D
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=
=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20=20
> +maintainable service configurations, will let user express any possible
^ missing =E2=80=9Cand=E2=80=9D
s/user/users/
[1]: <https://yhetil.org/guix-patches/665c4d2070de80af1d3594a268f0f6d3fb596=
d15.1639839498.git.public@HIDDEN/>
--=-=-=
Content-Type: application/pgp-signature; name="signature.asc"
-----BEGIN PGP SIGNATURE-----
iQJJBAEBCAAzFiEEAVhh4yyK5+SEykIzrPUJmaL7XHkFAmHC54IVHHB1YmxpY0B5
b2N0b2NlbGwueHl6AAoJEKz1CZmi+1x5K7YP/3l8xvhBxz0Wq6g4A58Ay8uhXJed
bXsTFZ6J63Yge76mSwT4cJk+cGOrpPprqYa/XpmGcGmx/W6KPG3VlZ+9hV7iFFpT
P5VZ9dAD4AqmBcQt3Bdzbwxd1Avc/A+KN6pHzG2egKvH+5nOS1XCxDbFOwUTi+Wx
HGeoXzwvZQEFIhBrZfpLeuFKviZiZi9eumSRfcrJqUk0evMMCFGvDkJ08TBCHYKS
aW64WKADeFv3BsJdpDMTjV/I4yGkGS+idsFNC4qUAuyK0rUha7Yeew8fY7GnNGud
NMFvJb2cCgtgDItcyMQqS1SJfvqOAN7dF9q40YW4FSIP8HpeeW4GBzNWzpg0XDr7
k2Vqiw/urNmewutu6eBfbYof3hEJLxUFtvoJ2hdebjAYTDTwoq9ltCE+g1HksISa
fkK5Almzf9WeDx41W4DkfSEJhEoX2XSwehQsKmTeugMYNfxreNQYk82wHE/ywrkv
MVEhChhrdUwfTgGrd14a3IEXzCNUmeVN78X1hCuX8zeuGBJTObk2pNzFpAydGwg+
TffGu+wgCJ4HMKu7dfi/UtTabzP0TcQ+r/sNSCMG9xbL45O22Z+7M6BV5sNJPieY
Tqz617IaBoVmF7FvquYcJQKwBsCgblEXL9epmkKqnVq7avzmTsCJJRtXukoMmgrA
JDwKXVBRkxq+1to/
=SQD6
-----END PGP SIGNATURE-----
--=-=-=--
guix-patches@HIDDEN:bug#52698; Package guix-patches.
Full text available.
Received: (at submit) by debbugs.gnu.org; 21 Dec 2021 10:21:50 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Tue Dec 21 05:21:50 2021
Received: from localhost ([127.0.0.1]:52439 helo=debbugs.gnu.org)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
id 1mzcHF-000431-9T
for submit <at> debbugs.gnu.org; Tue, 21 Dec 2021 05:21:50 -0500
Received: from lists.gnu.org ([209.51.188.17]:60124)
by debbugs.gnu.org with esmtp (Exim 4.84_2)
(envelope-from <andrew@HIDDEN>) id 1mzcHB-00042p-7r
for submit <at> debbugs.gnu.org; Tue, 21 Dec 2021 05:21:47 -0500
Received: from eggs.gnu.org ([209.51.188.92]:36764)
by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
(Exim 4.90_1) (envelope-from <andrew@HIDDEN>) id 1mzcHA-0004tx-Jg
for guix-patches@HIDDEN; Tue, 21 Dec 2021 05:21:45 -0500
Received: from [2a00:1450:4864:20::12e] (port=37669
helo=mail-lf1-x12e.google.com)
by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128)
(Exim 4.90_1) (envelope-from <andrew@HIDDEN>) id 1mzcH6-00085Q-JZ
for guix-patches@HIDDEN; Tue, 21 Dec 2021 05:21:43 -0500
Received: by mail-lf1-x12e.google.com with SMTP id bq20so27162380lfb.4
for <guix-patches@HIDDEN>; Tue, 21 Dec 2021 02:21:31 -0800 (PST)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=trop-in.20210112.gappssmtp.com; s=20210112;
h=from:to:cc:subject:date:message-id:mime-version;
bh=Q3lvO9QOQj5fjzFzj8pWQBmuoKSgsrEDi1eyD0+rGIk=;
b=8ID8hQrGTExMN04NwrbrQoC28TD/Hi9gOVmgIi076aZetzu+dCf6kjISePtAjleKCj
GTnBkTH6VWHzPmL/T3sCeZphV1ypccXrs17dTpgnLUt3lVzURX4VVSd/h6csZ+/QPrJY
X4L0NXKjY23rHj+axfMLlrvYNTbplfYGBQ7YYYhWC1Bxy73A92/AFa6XBowrVpfkV4s2
mkjyF9NjHniLmdZ+8vsrlVqSj07OC3ZaDAViJIhNZrVJQxv6TotsRQPo2BSbEtq7Jvlr
7WfYZPPsk3fRbVnin6HWqaKnPv4kCWAem9FGQOBOMGG3/mXCv5aGSisNSnp5REa+Y4Ia
u6UA==
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;
d=1e100.net; s=20210112;
h=x-gm-message-state:from:to:cc:subject:date:message-id:mime-version;
bh=Q3lvO9QOQj5fjzFzj8pWQBmuoKSgsrEDi1eyD0+rGIk=;
b=WUZaXBjXnICkhW/xFMAUWyetNq5kmpx9iIJAKx9VcYq+Pp/8ug/OVP8DzRl6YGdDDU
IgZifHOnZhfx/S7jxQO5lql2gJ2Tw4wwXUcGc33e324Md8xq/jx6N5vbOE9LYbge/QPY
a26CB2X7UUGOgRfl+/WV00uS8Y5MSeC+yNBpF2840YO4qgagGeQ9K79lXAnvF0xZ5pW7
kVLExi73iKkZ1xIfrCXCeunsPFDQIPx3GRXYveI86cS7fmuyCLxrXHvKndKrZMxjIdLv
sJ5sngESpbbiFsrM7gH0KWzqcasRlChtpLdxX8RXWCTm8KsB9YpXeYxlDU/gXxNmBki+
HPTQ==
X-Gm-Message-State: AOAM533djzV49dCsYe7rz8WuyJBporAeH8pQVJcg15ydQ+SXM3Xzjhri
8k43HxxzeJYHxeGyyV6XNtuqtw==
X-Google-Smtp-Source: ABdhPJxfK6hc9qoC5OWNEKFND7ppLg5lfSzqV5HyrNVzSYQaUHtSZvEhdIgt9ISghdtcpzyXuHD6iw==
X-Received: by 2002:a05:6512:31d5:: with SMTP id
j21mr2472563lfe.669.1640082089821;
Tue, 21 Dec 2021 02:21:29 -0800 (PST)
Received: from localhost (109-252-167-227.dynamic.spd-mgts.ru.
[109.252.167.227])
by smtp.gmail.com with ESMTPSA id j16sm2666997lfe.4.2021.12.21.02.21.28
(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);
Tue, 21 Dec 2021 02:21:29 -0800 (PST)
From: Andrew Tropin <andrew@HIDDEN>
To: guix-devel@HIDDEN, guix-patches@HIDDEN, Ludovic =?utf-8?Q?Court?=
=?utf-8?Q?=C3=A8s?= <ludo@HIDDEN>
Subject: [RFC PATCH] doc: Add Writing Service Configuration section.
Date: Tue, 21 Dec 2021 13:21:20 +0300
Message-ID: <87h7b2b6n3.fsf@HIDDEN>
MIME-Version: 1.0
Content-Type: multipart/signed; boundary="=-=-=";
micalg=pgp-sha512; protocol="application/pgp-signature"
X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::12e
(failed)
Received-SPF: none client-ip=2a00:1450:4864:20::12e;
envelope-from=andrew@HIDDEN; helo=mail-lf1-x12e.google.com
X-Spam_score_int: -10
X-Spam_score: -1.1
X-Spam_bar: -
X-Spam_report: (-1.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
DKIM_VALID=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RDNS_NONE=0.793,
SPF_HELO_NONE=0.001, SPF_NONE=0.001 autolearn=no autolearn_force=no
X-Spam_action: no action
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: submit
Cc: Xinglu Chen <public@HIDDEN>
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>,
<mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)
--=-=-=
Content-Type: text/plain
Content-Transfer-Encoding: quoted-printable
* guix.texi (Writing Service Configuration): New section.
=2D--
After reading the source code of different system services and implementing=
a
few of home services I decided to write down most important tips for
implementing guix service configurations. I belive having such a guideline
can simplify the development of new services and configurations for them, as
well as keeping those implementations consistent, which will simplify the l=
ife
for users too because they won't need to learn a different configuration
approaches for different services.
This section is not a final document, but a starting point for discussion a=
nd
further extension of the guideline. Feel free to raise a question, point t=
o a
mistake, make a suggestion or propose an idea.
Best regards,
Andrew Tropin
doc/guix.texi | 209 +++++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 205 insertions(+), 4 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index 333cb4117a..a48fb0e2b7 100644
=2D-- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -35652,10 +35652,11 @@ them in an @code{operating-system} declaration. =
But how do we define
them in the first place? And what is a service anyway?
=20
@menu
=2D* Service Composition:: The model for composing services.
=2D* Service Types and Services:: Types and services.
=2D* Service Reference:: API reference.
=2D* Shepherd Services:: A particular type of service.
+* Service Composition:: The model for composing services.
+* Service Types and Services:: Types and services.
+* Service Reference:: API reference.
+* Shepherd Services:: A particular type of service.
+* Writing Service Configurations:: A guideline for writing guix services.
@end menu
=20
@node Service Composition
@@ -35851,6 +35852,206 @@ There can be only one instance of an extensible s=
ervice type such as
Still here? The next section provides a reference of the programming
interface for services.
=20
+@node Writing Service Configurations
+@subsection Writing Service Configurations
+
+There are a lot of system and home services already written, but from
+time to time it's necessary to write one more. This section contains
+tips for simplifying this process, and should help to make service
+configurations and their implementations more consistent.
+
+@quotation Note
+If you find any exceptions or patterns missing in this section, please
+send a patch with additions/changes to @email{guix-devel@@gnu.org}
+mailing list or just start a discussion/ask a question.
+@end quotation
+
+@subsubheading Configuration Itself
+
+As we know from previous section a guix service can accept a value and
+be extended with additional values by other services. There are some
+cases, when the service accepts a list of pairs or some other values for
+example @code{console-font-service-type} accepts list of pairs (tty and
+font name/file) or @code{etc-service-type} accepts list of lists
+(resulting file name and file-like object), those services are kinda
+special, they are an intermediate helpers doing auxiliary work.
+
+However, in most cases a guix service is wrapping some software, which
+consist of package or a few packages, and configuration file or files.
+Therefore, the value for such service is quite complicated and it's hard
+to represent it with a just list or basic data type, in such cases we
+use a record. Each such record have -configuration suffix, for example
+@code{docker-configuration} for @code{docker-service-type} and a few
+different fields helping to customize the software. Configuration
+records for home services also have a @code{home-} prefix in their name.
+
+There is a module @code{gnu service configuration}, which contains
+helpers simplifying configuration definition process. Take a look at
+@code{gnu services docker} module or grep for
+@code{define-configuration} to find usage examples.
+
+@c Provide some examples, tips, and rationale behind @code{gnu service
+@c configuration} module.
+
+After a configuration record properly named and defined let's discuss
+how to name and define fields, and which approach to use for
+implementing the serialization code related to them.
+
+@subsubheading Configuration Record Fields
+
+@enumerate
+@item
+It's a good idea to have a field/fields for specifying package/packages
+being installed for this service. For example
+@code{docker-configuration} has @code{docker}, @code{docker-cli},
+@code{containerd} fields. Sometimes it make sense to make a field,
+which accepts a list of packages for cases, where an arbitrary list of
+plugins can be passed to the configuration. There are some services,
+which provide a field called @code{package} in their configuration,
+which is ok, but the way it done in @code{docker-configuration} is more
+flexible and thus preferable.
+
+@item
+Fields for configuration files, should be called the same as target
+configuration file name, but in kebab-case: bashrc for bashrc,
+bash-profile for bash_profile, etc. The implementation for such fields
+will be discussed in the next subsubsection.
+
+@item
+Other fields in most cases add some boilerplates/reasonable defaults to
+configuration files, turns on/off installation of some packages or
+provide other custom behavior. There is no any special requirements or
+recommendations here, but it's necessary to make it possible to disable
+all the effects of such fields to provide a user with an empty
+configuration and let them generate it from scratch with only field for
+configuration file.
+
+@end enumerate
+
+@subsubheading Fields for Configuration Files
+
+The field should accept a datastructure (preferably a combination of
+simple lists, alists, vectors, gexps and basic data types), which will
+be serialized to target configuration format, in other words it should
+provide an alternative lisp syntax, which can be later translated to
+target one, like SXML for XML. Such approach is quite flexible and
+simple, it requires to write serializer once for one configuration
+format and can be reused multiple times in different guix services.
+
+Let's take a look at JSON: we implement serialization function, which
+converts vectors to arrays, alists to objects (AKA dictionaries or
+associative arrays), numbers to numbers, gexps to the strings, file-like
+objects to the strings, which contains the path to the file in the
+store, @code{#t} to @code{true} and so on, and now we have all apps
+using JSON and YAML as a format for configurations covered. Maybe some
+fine-tunning will be needed for particular application, but the primary
+serilalization part is already finished.
+
+The pros and cons of such approach is inherited from open-world
+assumption. It doesn't matter if underlying applications provides new
+configuration options, we don't need to change anything in service
+configuration and its serialization code, it will work perfectly fine,
+on the other hand it harder to type check and structure check
+``compile-time'', and we can end up with configuration, which won't be
+accepted by target application cause of unexisting, misspelled or
+wrongly-typed options. It's possible to add those checks, but we will
+get the drawbacks of closed-world assumption: we need to keep the
+service implementation in-sync with app config options, and it will make
+impossible to use the same service with older/newer package version,
+which has a slightly different list of available options and will add an
+excessive maintanence load.
+
+However, for some applications with really stable configuration those
+checks can be helpful and should be implemented if possible, for some
+other we can implement them only partially.
+
+The alternative approach applied in some exitsting services is to use
+records for defining the structure of configuration field, it has the
+same downsides of closed-world assumption and a few more problems:
+
+@enumerate
+@item
+It has to replicate all the available options for the app (sometimes
+hundreds or thousands) to allow user express any configuration they
+wants.
+@item
+Having a few records, adds one more layer of abstraction between service
+configuration and resulting app config, including different field
+casing, new semantic units.
+@c provide examples?
+@item
+It harder to implement optional settings, serialization becomes very
+ad-hoc and hard to reuse among other services with the same target
+config format.
+@end enumerate
+
+Exceptions can exist, but the overall idea is to provide a lispy syntax
+for target configuration. Take a look at sway example configuration
+(which also can be used for i3). The following value of @code{config}
+field of @code{home-sway-configuration}:
+
+@example
+`((include ,(local-file "./sway/config"))
+ (bindsym $mod+Ctrl+Shift+a exec emacsclient -c --eval "'(eshell)'")
+ (bindsym $mod+Ctrl+Shift+o "[class=3D\"IceCat\"]" kill)
+ (input * ((xkb_layout us,ru)
+ (xkb_variant dvorak,))))
+@end example
+
+would yield something like:
+
+@example
+include /gnu/store/408jwvh6wxxn1j85lj95fniih05gx5xj-config
+bindsym $mod+Ctrl+Shift+a exec emacsclient -c --eval '(eshell)'
+bindsym $mod+Ctrl+Shift+o [class=3D"IceCat"] kill
+input * @{
+ xkb_layout us,ru
+ xkb_variant dvorak,
+@}
+@end example
+
+The mapping between scheme code and resulting configuration is quite
+obvious. The serialization code with some type and structure checks
+takes less than 70 lines and every possible sway/i3 configuration can be
+expressed using this field.
+
+@subsubheading Let User Escape
+Sometimes user already have a configuration file for an app, make sure
+that it is possible to reuse it directly without rewriting. In the
+example above, the following snippet allows to include already existing
+config to the newly generated one utilizing @code{include} directive of
+i3/sway config language:
+
+@example
+(include ,(local-file "./sway/config"))
+@end example
+
+When building a resulting config the file-like objects are substituted
+with a path of the file in the store and sway's @code{include} loads
+this file during startup. The way file-like objects are treated here
+also allows to specify paths to plugins or other binary files like:
+@code{(load-plugin ,(file-append plugin-package "/share/plugin.so"))}
+(the example value for imaginary service configuration config file
+field).
+
+In some cases target configuration language may not have such
+@code{include} directive and can't provide such a functionallity, to
+workaround it we can do the following trick:
+
+@example
+`(#~(call-with-input-file
+ #$(local-file "./sway/config")
+ (@@ (ice-9 textual-ports) get-string-all)))
+@end example
+
+G-expressions get serialized to its values, and the example above reads
+the content of the file-like object and inserts it in the resulting
+configuration file.
+
+Following these simple rules will help to make a simple, consistent and
+maintainable service configurations, will let user express any possible
+needs and reuse existing configuration files.
+
@node Service Reference
@subsection Service Reference
=20
=2D-=20
2.34.0
--=-=-=
Content-Type: application/pgp-signature; name="signature.asc"
-----BEGIN PGP SIGNATURE-----
iQJDBAEBCgAtFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmHBqqAPHGFuZHJld0B0
cm9wLmluAAoJECII0glYwd6wzU0P/iXz2f7KJa79dV9MlD+7lGC2U90W9kwDXVLe
nnL0bPaCLIv4rmvNkjOJWEhMLgUh/i/RAL82I6hWLwXgynimBPeBLqq4YoxJLRuG
oqySKO/sFOMH29Ht71QW7gJ1KggfA2EjTnUB06z7ysEBDzQHKasDitY5bDxr9zrg
mtXqezjMQkVaoWTxi0HIDTtE/jUfTCYbxSr9qqyrJA0uRolT5YQR5iT0Zy3BzoFq
38vwcTAttqhaLXfrJk5Jk/kE/mrnJ6xes1+q2m4yMXcCj3K1qXfL/8+4/ePEM9dF
tQZV2n/IplVvnjbmy9JDng9O/zCddEq2MrKWnb8cGXxDs+C9GhvVcTRGPFRso/rq
0obrflYvPGmMZ4kftZMwfqDC2O8pi5MF10xCXjxKYRWLyVcLSc7mO0C817D+xTh8
vHxXxRizbMEqXvmNXz1Bfm6XmT1Ki/NcjYRU9UM45ss/35OWrWXrzd7Dg3qKfkwI
mLn5yV03xLI2T+3KFmDDEdQkGj6SCnnfmw8wiQVrv+8NLG69p6Z3Q7LDK0bGrVuu
TO8rXx7R85zKUfPaFz9tx0xDlDp2lxinZK995v2geH49ykfPUeg+aii9/Fjlcu/1
HuDnSDcH8h/Ix3kuRtql1EIzmKTbgfPLKKKUE3PylS6CNKKMu8AYgpiKNO7J/EyB
plWLIyVb
=YYUo
-----END PGP SIGNATURE-----
--=-=-=--
Andrew Tropin <andrew@HIDDEN>:guix-patches@HIDDEN.
Full text available.guix-patches@HIDDEN:bug#52698; Package guix-patches.
Full text available.
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997 nCipher Corporation Ltd,
1994-97 Ian Jackson.