From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id iDSFHc52xGFvAAEAgWs5BA (envelope-from ) for ; Thu, 23 Dec 2021 14:17:02 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id YJ5HGc52xGFvYQAAB5/wlQ (envelope-from ) for ; Thu, 23 Dec 2021 13:17:02 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id E12F3E884 for ; Thu, 23 Dec 2021 14:17:01 +0100 (CET) Received: from localhost ([::1]:55490 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n0Nxt-0001hD-0m for larch@yhetil.org; Thu, 23 Dec 2021 08:17:01 -0500 Received: from eggs.gnu.org ([209.51.188.92]:60278) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n0Nxd-0001eI-BD for guix-devel@gnu.org; Thu, 23 Dec 2021 08:16:45 -0500 Received: from [2a00:1450:4864:20::12b] (port=35796 helo=mail-lf1-x12b.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1n0NxZ-0006Sp-Va for guix-devel@gnu.org; Thu, 23 Dec 2021 08:16:45 -0500 Received: by mail-lf1-x12b.google.com with SMTP id g11so12386431lfu.2 for ; Thu, 23 Dec 2021 05:16:41 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=trop-in.20210112.gappssmtp.com; s=20210112; h=from:to:subject:in-reply-to:references:date:message-id:mime-version; bh=x3FypJ6RuhzcB3uftQ1N78plGYISSV4Y3+3s0UDa4jU=; b=gS9mvgHMgnt33xCYJZ/VNvdx9sCaMcu9yEmnFUBZRR/BN5HtNWj93Jnl+PuYGjlQA6 8OuSzXaUH6KAgP+jU95p8LW3fPh43j9gX2GB3nOSEg4asj+d7N2Y4n9K79p/hZVmylWp 3JqPUM6x6LU6jG3F7P3759+j8+IpvFcydT93Rf1rShzYs+kiLqZ5lXVXUNSUmrncbjur frE4ZFeH2iQJLXqWRNkAw8ZcdQhhBI9RYNqTLbH01wSNoJ9DrNC6hX/jKuvpeWSoReTM daV+NSYKtoR3yuCSlOeRMUkv6HqMZOOXGgr2Rq0gY4tU2bGrHrNfY/bH9i3M8IUczv6e ZlAw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:subject:in-reply-to:references:date :message-id:mime-version; bh=x3FypJ6RuhzcB3uftQ1N78plGYISSV4Y3+3s0UDa4jU=; b=orIr5xIYzREwAyv+VytH8LuP4wscI8ECqr73NamwSRK98uUa2rsMmVemUepgrpxQkf NPoyNq5VoJYXe0K+eP2RtXjgQ9fmr4gtDV9k3jLbn6LZpxBKwxa1DGrc4nObWVH8FYaA /mOmbhpyPugSQKkvtEQBUp//AtS8LbonlKrE/h0f0x/PcD6v0Vk0zLHg0zXXiGjU9J4L aQFm/XrVVngyF7muJKohGp1iVmmq1D/cnN7tERa6QPtiyjgoYYSZBeV1PB5s1RGPauHL NgUYF/R6B3jdB0pWdWkYIw+St3yruPdXoK+XHN3vNG9cuIrwtf8GI3ebGEKzxil85KL2 Ivaw== X-Gm-Message-State: AOAM531RW378E/20i5P2CXooox0PYLstOzzKSEHkL/iACXRPQlJOE+WG KdB9LkuJEzbpbD/7JUDjh2X/jMoEIWk9xQ== X-Google-Smtp-Source: ABdhPJzM0pMEBzd7sDRFDWh/P/wZLbmwkFqT1mBjkbtiWY6fdAAENTVUvZMCVowbi+RqSAzGJbaXRg== X-Received: by 2002:ac2:4857:: with SMTP id 23mr1821252lfy.217.1640265398835; Thu, 23 Dec 2021 05:16:38 -0800 (PST) Received: from localhost (109-252-167-227.dynamic.spd-mgts.ru. [109.252.167.227]) by smtp.gmail.com with ESMTPSA id z18sm500690lfd.8.2021.12.23.05.16.37 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 23 Dec 2021 05:16:38 -0800 (PST) From: Andrew Tropin To: Xinglu Chen , guix-devel@gnu.org, guix-patches@gnu.org, Ludovic =?utf-8?Q?Court=C3=A8s?= Subject: Re: [RFC PATCH] doc: Add Writing Service Configuration section. In-Reply-To: <87k0fxvx4t.fsf@yoctocell.xyz> References: <87k0fxvx4t.fsf@yoctocell.xyz> Date: Thu, 23 Dec 2021 16:16:35 +0300 Message-ID: <87h7az5umk.fsf@trop.in> 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::12b (failed) Received-SPF: none client-ip=2a00:1450:4864:20::12b; envelope-from=andrew@trop.in; helo=mail-lf1-x12b.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-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1640265422; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=x3FypJ6RuhzcB3uftQ1N78plGYISSV4Y3+3s0UDa4jU=; b=bFoDseVYczKqIIE6T3w6yZo13Ge6a4WiUUWTkbrx9vyFEFVrXYMr9v7gPD2XPqO4R07ls0 83eCAz6v7wx+/oCpj6ixv5Vl9G96WwR1sDVIy3kKTQHhu3Y/vh+UbgtNIUt71CeE/8tZCW JGfGsaHxyYErB2IZkk6Ezo9cwIAqhx9a/RyDn4iIZkERA6j9mBoa/o63FoVTYJQDdxtGR0 gF/s11iI6fAGky0gKmsAH7YJdGwWEZrEpwAIEe4FutGZRErxKVjtVBONug8q+HsOygccpq jFp5UhOWsHrhAJNwAFPqszSO0z2AlMGbdUAQkkIo5VmQyOfo8XSkSAKJTLn3sw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1640265422; a=rsa-sha256; cv=none; b=qfQLBAjj3UfmpzDismciFqTZfSMln9mSZjSYkhsnWgL8iZWGTTqjfihmUk9oWmLGbsAdBa 32I6SiXtV7+O8HWl3a7oSw/ULTT17yy7A+KP6tIwgOmrzosemRLw+DjOxQNkjUkaQglygs e7O20Sc+FAVrCZqsGyel2YzR88Rdu3Ehz+tHSTzsjm+70B7NxHbHucNuzTnzPswxIj2AuP pfQD/wJ7bAWRR0yX3hn5l2skXmQ+cV9Jd1Bq/LM577pjJXzrjxolWuLbJ+iuLwAlk0yDSS hYEGwEOrjkrtcVk2/5eLhwfJGbY0rKBuJ2DDkZNleihtCj9vUlBXF6vVQq1BFA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=trop-in.20210112.gappssmtp.com header.s=20210112 header.b=gS9mvgHM; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -7.35 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=trop-in.20210112.gappssmtp.com header.s=20210112 header.b=gS9mvgHM; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: E12F3E884 X-Spam-Score: -7.35 X-Migadu-Scanner: scn0.migadu.com X-TUID: z+oyWSaiHXAJ --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 2021-12-22 09:53, Xinglu Chen wrote: > Am Dienstag, der 21. Dezember 2021, um 13:21 +032, schrieb Andrew Tropin = : > >> * guix.texi (Writing Service Configuration): New section. >> --- >> After reading the source code of different system services and implement= ing a >> few of home services I decided to write down most important tips for >> implementing guix service configurations. I belive having such a guidel= ine >> can simplify the development of new services and configurations for them= , as >> well as keeping those implementations consistent, which will simplify th= e 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 discussio= n and >> further extension of the guideline. Feel free to raise a question, poin= t 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 service= s. >> @end menu >>=20=20 >> @node Service Composition >> @@ -35851,6 +35852,206 @@ There can be only one instance of an extensibl= e 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 = comes after > =E2=80=9CShepherd Services=E2=80=9D, but this doesn=E2=80=99t seem to be = the case here. > Done. >> +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 s= ection > on contributing to the project, see =E2=80=9C17 Contributing=E2=80=9D. > Not necessary, but I would keep it for a few months to make people more involved in the polishing of this guide. >> +@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 Done. > > 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 I mean service, which is instantiated from some service type. > > =E2=80=A6 a value, usually some kind of configuration > record (@pxref{RELEVANT NODE(s)}) changed it to service value and added this note. > > ? > >> +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 b= y other > services (@pxref{Service Composition}). > Done. >> +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 '= @anchor': 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. Slightly rewrote this paragraph. I don't know how to reference index entries (if it possible at all), so I added anchors for them. > > Also, is should there be any preference for using alists or list of > lists or vice versa? Now it should be clear that a -configuration record is preferable as a service value, lists and alists are special cases for auxiliray services and shouldn't be used in most cases. > >> +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 file= s.=E2=80=9D > Done. >> +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= manual > > @code{-configuration} or maybe @samp{-configuration} Done. > >> +@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 = record > type named @code{docker-configuration}, which contains a fields used > to configure Docker. > Done. >> +Configuration >> +records for home services also have a @code{home-} prefix in their name. > ^ missing =E2=80=9Cshould=E2=80=9D Done. > >> +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. > Saw it, I'll try to review and comment on it, when I'll get some spare time. I'll keep this comment for now, and after the section about gnu service configuration module is merged, we will add links to it and provide more info and examples on implementing actual configurations. > >> +After a configuration record properly named and defined let's discuss > ^ =E2=80=9C=E2=80=A6has been=E2=80=A6=E2= =80=9D Done. > >> +how to name and define fields, and which approach to use for > ^ missing =E2=80=9Cthe=E2=80=9D Done. > >> +implementing the serialization code related to them. > > =E2=80=9Cserialization=E2=80=9D doesn=E2=80=99t seem to be mentioned anyw= here 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 string= s, which > will be put into one or more configuration files. Added a parapgraph about serialization. > >> +@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 > Done. >> +@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. Done. > >> +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 clea= r. More flexible comparing to just one package field, because it makes it easier to define a configuration for software requiring a few packages like docker. `docker-package` is a good idea, which makes it very clear what the content of this field should be, however just `docker` should be enough we already have a type information for this field in documentation and this pattern is already applied in a few dozens of different services. > >> +@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 = the field be > named =E2=80=98file-ext=E2=80=99? Added a footnote, provided more expressive examples @code{bashrc} for @file{.bashrc}, @code{bash-profile} for @file{.bash_profile}, @code{tmux-conf} for @file{tmux.conf}, etc. > >> +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=98ext= ra-config=E2=80=99, or > =E2=80=98extra-options=E2=80=99 field. In most cases these just take a s= tring 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? > I find this pattern purely-established (content vs conf vs options), unclear (you can never know where this extra content will be inserted until you take a look at implementation of serialization function) and uneccesary (we do not need extra-* fields because we can add any extra content using G-expression inside our primary configuration, see sway example below). > >> +@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=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 def= aults? > Kind of. See guix-default? for home-bash-service-type. Also, fields like aliases and environment-variables are of the same category I describe here. Added them as an example of such fields. > >> +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=9Cenabl= e/disabled=E2=80=9D sounds > better. Done. > >> +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 gene= rate it from > scratch with only field for configuration file=E2=80=9D.=20=20 The good examples of the bad behavior are alsa and nginx service types, they always provide some boilerplate with reasonably good default configuration, but you can't alter it by setting some fields to #f or some other values. For nginx it's only partially true, you actually can use `file` field, but it will alter the effect of all other fields and will just use the file as nginx.conf, kinda conforms what I'm asking here, but makes all other fields useless. Added the following explanation to this item: =2D-8<---------------cut here---------------start------------->8--- 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. =2D-8<---------------cut here---------------end--------------->8--- > > 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 optio= ns, but these > obviously don=E2=80=99t cover all the options available in /etc/ssh/sshd_= config, > which is why there is an =E2=80=9Cescape hatch=E2=80=9D, =E2=80=98extra-c= ontent=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. > This is mentioned below, as well as the problem of closed-world assumption. Software should be fully configurable with field for respective config file, escape hatch should be a part of this field. Escape hatch is necessary to allow to reuse already existing configuration, but not to provide configuration, which can't be expressed by respective configuration field. >> +@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. > Done. > >> +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. Done > >> +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)? > Yep. Done. > >> +simple, it requires to write serializer once for one configuration > ^ =E2=80=9Cone=E2=80=9D or =E2=80=9Cyou=E2=80=9D Sounds better for me without one or you. > >> +format and can be reused multiple times in different guix services. > > Capitalize =E2=80=9Cguix=E2=80=9D. Done. > >> +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. Agree. > > There should be a link =E2=80=9Cfile-like object=E2=80=9D since it may be= unknown for > many. Done. > >> +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? JSON is a subset of YAML, so having a serializer for JSON makes it possible to generate configurations for many YAML-flavored applications. However, it maybe not that clear and important. Will remove it. > >> +fine-tunning will be needed for particular application, but the primary >> +serilalization part is already finished. > > =E2=80=9Cserialization=E2=80=9D typo. Done > >> +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=20 > What do you mean by =E2=80=9Copen-world assumption=E2=80=9D? https://en.wikipedia.org/wiki/Open-world_assumption https://en.wikipedia.org/wiki/Closed-world_assumption They often used when designing programming languages or DSLs. > >> +configuration options, we don't need to change anything in service > ^ =E2=80=9Ct= he=E2=80=9D Done. > >> +configuration and its serialization code, it will work perfectly fine, > A full stop should probably be used here ^ Done. > >> +on the other hand it harder to type check and structure check > ^ =E2=80=9Cis=E2=80=9D Done. >> +``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 Done > >> +accepted by target application cause of unexisting, misspelled or > ^ =E2=80=9Cthe=E2=80=9D > > s/application/program/ :-) > s/cause/because/ Changed `cause of` to `due to`. > >> +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/ Done. > >> +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 Done. > >> +wants. > > s/wants/want/ Done. > > >> +@item >> +Having a few records, adds one more layer of abstraction between service > ^ spurious comma Done. > > >> +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. > Yes it is more Scheme-flavored, but it doesn't mean good. I can write a good rationale on this topic, but will do it next time, now I'll just give you an example, which should be relevant to you: Imagine writing an importer (for `guix home import` for example) from XML to SXML, now imagine that instead of SXML we have Scheme-like configuration. It hours and days more work. Implementing and maintaining such Scheme-flavored configuration is a big pain, especially if software still changes and config options isn't stable yet. Moreover, it doesn't give too much benifits, some compile time checks with quite poor type system, which gives some safety feeling. There are better solutions for that like clojure.spec in Clojure. Also, event not having guile.spec, the same checks can be implemented with basic pattern matching. IMO, it not worth it to stick to Scheme-flavor for configuration fields. >> +@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. Done. > >> +(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. Don't think it's a big problem. We can treat it as an imaginary example 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. Done. > >> +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-configu= ration=E2=80=99 > isn=E2=80=99t in Guix proper, users have no idea of where to look if they= want > to see the source code. home-sway-configuration is complete and it won't take much time to upstream it, when we finish with this guideline. > > >> +expressed using this field. >> + >> +@subsubheading Let User Escape > > I suggest =E2=80=9CEscape Hatches=E2=80=9D since the term is already ment= ioned 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/ Done. > >> +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 Done. > >> +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. Done. > > >> +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 Done. > >> +@code{(load-plugin ,(file-append plugin-package "/share/plugin.so"))} > > This should probably be put in its own @lisp block. Done. > >> +(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 missin= g =E2=80=9Can=E2=80=9D ^ Done. >> +@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. Done. > > 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-m= odules=E2=80=99 at the > beginning of the file. It's @, not @@. You are right, use-modules is prefered in most cases, but for this example I think it's ok. > >> +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 o= f 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}. > Done. > >> +Following these simple rules will help to make a simple, consistent and > ^ spurious =E2=80=9Ca= =E2=80=9D Done. > >> +maintainable service configurations, will let user express any possible > ^ missing =E2=80=9Cand=E2=80=9D > > s/user/users/ Done. > > [1]: Will send a second version in a separate email. =2D-=20 Best regards, Andrew Tropin --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJDBAEBCgAtFiEEKEGaxlA4dEDH6S/6IgjSCVjB3rAFAmHEdrMPHGFuZHJld0B0 cm9wLmluAAoJECII0glYwd6w8GoP/jwhRwC4Obv2cBdLhu3xz/qr7If4nrygnh/U S2AnTu8TeRTbIcoYDCi286gH4xQ230bNNvedkvMcX+cjj/gg4zU6Fy9H9s0ubwbn Dzep0s7KYiMMBrVhGSRJIW/mhcOhd4HNv+XB53YqrBfAmCny360mIdAErQvuc8ln ojrSKWpq3E1JDpQ0E0BYQI3Lv1Gb0pyQG3QEsxBlMpzFJB5PKwSZu7BmgNSD5Bv2 ZY37vuSi7Wy0vkBDJfV75KBCVACcDY8BUZgEhXUZ92YRVa7Qx/FT7Fd73tzRsnF9 EqoiKFT97jVY3typkEa8VDS/dUt6VfztVR4VwuhtgQ8LfSSzKPuno7PqbyxicdE/ HBULGrSszjP1SrCKzGMpjuJj6HCTwPGmsTrsGWfQrltXG5/pZoT/41oojrP5zHCk Cx1AU08ZP56VmOaMGSf1odYJ2Z1vrznk7nvM2SggVihnquMQekHE/YBgPsGXzPm4 MIwUaqv2y/oKlHnWaYh/Iwuxjys6yoyEBWLl5Yo/2YKOTLetqVAQ7tRg8PQP0+vB 5CUmPA0X4xD0iHnCRkinUk/SXhfBgjA8Dnh9Uh6aBotvX2PGheeVJAbhnPpkg40i joQwV0kJq8blrg8jY9OgN/tPYo8GX9YTEpXK5ryizj9I5r9s/0wKxGPPIBRb4r3c s8uAsv4a =wCJU -----END PGP SIGNATURE----- --=-=-=--