From unknown Wed Sep 24 05:11:10 2025 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration). Resent-From: Xinglu Chen Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Sat, 18 Dec 2021 15:13:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 52600@debbugs.gnu.org Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , Maxim Cournoyer , Andrew Tropin X-Debbugs-Original-To: guix-patches@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.16398403808403 (code B ref -1); Sat, 18 Dec 2021 15:13:02 +0000 Received: (at submit) by debbugs.gnu.org; 18 Dec 2021 15:13:00 +0000 Received: from localhost ([127.0.0.1]:43586 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mybOO-0002BS-30 for submit@debbugs.gnu.org; Sat, 18 Dec 2021 10:13:00 -0500 Received: from lists.gnu.org ([209.51.188.17]:45140) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mybOL-0002BJ-Rh for submit@debbugs.gnu.org; Sat, 18 Dec 2021 10:12:58 -0500 Received: from eggs.gnu.org ([209.51.188.92]:45082) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mybOG-0004UH-H6 for guix-patches@gnu.org; Sat, 18 Dec 2021 10:12:55 -0500 Received: from h87-96-130-155.cust.a3fiber.se ([87.96.130.155]:37554 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 ) id 1mybOD-0007Dr-Ob; Sat, 18 Dec 2021 10:12:52 -0500 From: Xinglu Chen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=yoctocell.xyz; s=mail; t=1639840361; bh=yHmI8mrHsfWr/ITSy6dOpUUJ0laUd4YGDTAHiUKIMXo=; h=From:To:Cc:Subject:Date; b=GMc/ucYF1EUvCurvpxlS60/8R2VLMUvTq1nn0pM8xquH/7Iuxhk/XxwGS5ib2NQY6 RPowxXCD784m33B+h2BINdSHVbGqxLHqow4Ca+/e0axBqOmRn2dbFOULBoGA9/fhoJ Ab9Nah5w8tQd80YuOmowqKpLlIytrUldLu+qhKjg= Message-Id: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> Date: Sat, 18 Dec 2021 16:12:38 +0100 MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=87.96.130.155; envelope-from=public@yoctocell.xyz; helo=mail.yoctocell.xyz X-Spam_score_int: 53 X-Spam_score: 5.3 X-Spam_bar: +++++ X-Spam_report: (5.3 / 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.498, FROM_SUSPICIOUS_NTLD_FP=0.295, PDS_OTHER_BAD_TLD=1.997, PDS_RDNS_DYNAMIC_FP=0.001, RCVD_IN_PBL=3.335, RDNS_DYNAMIC=0.982, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, TO_NO_BRKTS_DYNIP=0.245 autolearn=no autolearn_force=no X-Spam_action: reject X-Spam-Score: 1.7 (+) 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: * guix.texi (Complex Configurations): New node. --- Hi! This patch documents the complex beast that is the (gnu services configuration) module. I only documented the things that existed before the Guix Home merge, though. There were a lot of things to docu [...] Content analysis details: (1.7 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_FP From abused NTLD 0.5 FROM_SUSPICIOUS_NTLD From abused NTLD -0.0 RCVD_IN_MSPIKE_WL Mailspike good senders X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.1 (/) * guix.texi (Complex Configurations): New node. --- Hi! This patch documents the complex beast that is the (gnu services configuration) module. I only documented the things that existed before the Guix Home merge, though. There were a lot of things to document, and I hope that my explanations aren=E2=80=99t too confusing (It took me a whil= e to wrap my head around all of this). :-) What is still missing is some kind of style guide for writing Guix services: When should one use (gnu services configuration) vs plain (guix records)? Should we try to create bindings for all config options or should we provide an =E2=80=9Cescape hatch=E2=80=9D for users? I would personally prefer if most (if not all) services were written using (gnu services configuration), but I don=E2=80=99t really think refact= oring existing services would really be worth it. But that=E2=80=99s another dis= cussion. doc/guix.texi | 372 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 372 insertions(+) diff --git a/doc/guix.texi b/doc/guix.texi index aca88cdada..79b87d2eac 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -383,6 +383,7 @@ * Service Types and Services:: Types and services. * Service Reference:: API reference. * Shepherd Services:: A particular type of service. +* Complex Configurations:: Defining bindgs for complex configurations. =20 Installing Debugging Files =20 @@ -35656,6 +35657,7 @@ * Service Types and Services:: Types and services. * Service Reference:: API reference. * Shepherd Services:: A particular type of service. +* Complex Configurations:: Defining bindgs for complex configurations. @end menu =20 @node Service Composition @@ -36389,6 +36391,376 @@ This service represents PID@tie{}1. @end defvr =20 +@node Complex Configurations +@subsection Complex Configurations +@cindex complex configurations +Some programs might have rather complex configuration files or formats, +and to make it easier to create Scheme bindings for these configuration +files, you can use the utilities defined in the @code{(gnu services +configuration)} module. + +The main utility is the @code{define-configuration} macro, which you +will use to define a Scheme record type (@pxref{Record Overview,,, +guile, GNU Guile Reference Manual}). The Scheme record will be +serialized to a configuration file by using @dfn{serializers}, which are +procedures that take some kind of Scheme value and returns a +G-expression (@pxref{G-Expressions}), which should, once serialized to +the disk, return a string. More details are listed below. + +@deffn {Scheme Syntax} define-configuration @var{name} @var{clause1} @ +@var{clause2} ... +Create a record type named @code{@var{name}} that contains the +fields found in the clauses. + +A clause can have one the following forms + +@example +(@var{field-name} + (@var{type} @var{default-value}) + @var{documentation}) +=20 +(@var{field-name} + (@var{type} @var{default-value}) + @var{documentation} + @var{serializer}) + +(@var{field-name} + (@var{type}) + @var{documentation}) + +(@var{field-name} + (@var{type}) + @var{documentation} + @var{serializer}) +@end example + +@var{field-name} is an identifier that denotes the name of the field in +the generated record. + +@var{type} is the type of the value corresponding to @var{field-name}; +since Guile is untyped, a predicate +procedure---@code{@var{type}?}---will be called on the value +corresponding to the field to ensure that the value is of the correct +type. This means that if say, @var{type} is @code{package}, then a +procedure named @code{package?} will be applied on the value to make +sure that it is indeed a @code{} object. + +@var{default-value} is the default value corresponding to the field; if +none is specified, the user is forced to provide a value when creating +an object of the record type. + +@c XXX: Should these be full sentences or are they allow to be very +@c short like package synopses? +@var{documentation} is a string formatted with Texinfo syntax which +should provide a description of what setting this field does. + +@var{serializer} is the name of a procedure which takes two arguments, +the first is the name of the field, and the second is the value +corresponding to the field. The procedure should return a string or +G-expression (@pxref{G-Expressions}) that represents the content that +will be serialized to the configuration file. If none is specified, a +procedure of the name @code{serialize-@var{type}} will be used. + +A simple serializer procedure could look like this. + +@lisp +(define (serialize-boolean field-name value) + (let ((value (if value "true" "false"))) + #~(string-append #$field-name #$value))) +@end lisp=20=20 + +In some cases multiple different configuration records might be defined +in the same file, but their serializers for the same type might have to +be different, because they have different configuration formats. For +example, the @code{serialize-boolean} procedure for the Getmail service +would have to be different for the one for the Transmission service. To +make it easier to deal with this situation, one can specify a serializer +prefix by using the @code{prefix} literal in the +@code{define-configuration} form. This means that one doesn't have to +manually specify a custom @var{serializer} for every field. + +@lisp +(define (foo-serialize-string field-name value) + @dots{}) + +(define (bar-serialize-string field-name value) + @dots{}) +=20=20 +(define-configuration foo-configuration + (label + (string) + "The name of label.") + (prefix foo-)) + +(define-configuration bar-configuration + (ip-address + (string) + "The IPv4 address for this device.") + (prefix bar-)) +@end lisp + +However, in some cases you might not want to serialize any of the values +of the record, to do this, you can use the @code{no-serialization} +literal. There is also the @code{define-configuration/no-serialization} +macro which is a shorthand of this. + +@lisp +;; Nothing will be serialized to disk. +(define-configuration foo-configuration + (field + (string "test") + "Some documentation.") + (no-serialization)) + +;; The same thing as above. +(define-configuration/no-serialization bar-configuration + (field + (string "test") + "Some documentation.")) +@end lisp=20=20=20 +@end deffn + +@deffn {Scheme Syntax} define-maybe @var{type} +Sometimes a field should not be serialized if the user doesn=E2=80=99t spe= cify a +value. To achieve this, you can use the @code{define-maybe} macro to +define a ``maybe type''; if the value of a maybe type is set to the +@code{disabled}, it will not be serialized. + +When defining a ``maybe type'', the corresponding serializer for the +regular type will be used by default. For example, a field of type +@code{maybe-string} will be serialized using the @code{serialize-string} +procedure by default, you can of course change this by specifying a +custom serializer procedure. Likewise, the type of the value would have +to be a string, unless it is set to the @code{disabled} symbol. + +@lisp +(define-maybe string) + +(define (serialize-string field-name value) + @dots{}) + +(define-configuration baz-configuration + (name + ;; Nothing will be serialized by default. If set to a string, the + ;; `serialize-string' procedure will be used to serialize the string. + (maybe-string 'disabled) + "The name of this module.")) +@end lisp + +Like with @code{define-configuration}, one can set a prefix for the +serializer name by using the @code{prefix} literal. + +@lisp +(define-maybe integer + (prefix baz-)) + +(define (baz-serialize-interger field-name value) + @dots{}) +@end lisp + +There is also the @code{no-serialization} literal, which when set means +that no serializer will be defined for the ``maybe type'', regardless of +its value is @code{disabled} or not. +@code{define-maybe/no-serialization} is a shorthand for specifying the +@code{no-serialization} literal. + +@lisp +(define-maybe/no-serialization symbol) + +(define-configuration/no-serialization test-configuration + (mode + (maybe-symbol 'disabled) + "Docstring.")) +@end lisp +@end deffn + +@deffn {Scheme Procedure} serialize-configuration @var{configuration} @ +@var{fields} +Return a G-expression that contains the values corresponding to the +@var{fields} of @var{configuration}, a record that has been generated by +@code{define-configuration}. The G-expression can then be serialized to +disk by using something like @code{mixed-text-file}. +@end deffn + +@deffn {Scheme Procedure} validate-configuration @var{configuration} +@var{fields} +Type-check @var{fields}, a list of field names of @var{configuration}, a +configuration record created by @code{define-configuration}. +@end deffn + +@deffn {Scheme Procedure} empty-serializer @var{field-name} @var{value} +A serializer that just returns an empty string. The +@code{serialize-package} procedure is an alias for this. +@end deffn + +Once you have defined a configuration record, you will most likely also +want to document it so that other people know to use it. To help with +that, there are two procedures, both of which are documented below. + +@deffn {Scheme Procedure} generate-documentation @var{documentation} @ +@var{documentation-name} +Generate a Texinfo fragment from the docstrings in @var{documentation}, +a list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}. +@var{label} should be a symbol and should be the name of the +configuration record. @var{fields} should be a list of all the fields +available for the configuration record. + +@var{sub-documentation} is a @code{(@var{field-name} +@var{configuration-name})} tuple. @var{field-name} is the name of the +field which takes another configuration record as its value, and +@var{configuration-name} is the name of that configuration record. + +@var{sub-documentation} is only needed if there are nested configuration +records. For example, the @code{getmail-configuration} record +(@pxref{Mail Services}) accepts a @code{getmail-configuration-file} +record in one of its @code{rcfile} field, therefore documentation for +@code{getmail-configuration-file} is nested in +@code{getmail-configuration}. + +@lisp +(generate-documentation + `((getmail-configuration ,getmail-configuration-fields + (rcfile getmail-configuration-file)) + @dots{}) + 'getmail-configuration) +@end lisp + +@var{documentation-name} should be a symbol and should be the name of +the configuration record. + +@end deffn + +@deffn {Scheme Procedure} configuration->documentation +@var{configuration-symbol} +Take @var{configuration-symbol}, the symbol corresponding to the name +used when defining a configuration record with +@code{define-configuration}, and print the Texinfo documentation of its +fields. This is useful if there aren=E2=80=99t any nested configuration r= ecords +since it only prints the documentation for the top-level fields. +@end deffn + +As of right now, there is no automated way to generate documentation for +and configuration records and put them in the manual. Instead, every +time you make a change to the docstrings of a configuration record, you +have to manually call @code{generate-documentation} or +@code{configuration->documentation}, and paste the output into the +@file{doc/guix.texi} file. + +@c TODO: Actually test this +Below is an example of a record type created using +@code{define-configuration} and friends. + +@lisp +(use-modules (gnu services) + (guix gexp) + (gnu services configuration) + (srfi srfi-26) + (srfi srfi-1)) + +;; Turn field names, which are Scheme symbols into strings +(define (uglify-field-name field-name) + (let ((str (symbol->string field-name))) + ;; field? -> is-field + (if (string-suffix? "?" str) + (string-append "is-" (string-drop-right str 1)) + str))) + +(define (serialize-string field-name value) + #~(string-append #$(uglify-field-name field-name) " =3D " #$value "\n")) + +(define (serialize-integer field-name value) + (serialize-string field-name (number->string value))) + +(define (serialize-boolean field-name value) + (serialize-string field-name (if value "true" "false"))) + +(define (serialize-contact-name field-name value) + #~(string-append "\n[" #$value "]\n")) + +(define (list-of-contact-configurations? lst) + (every contact-configuration? lst)) + +(define (serialize-list-of-contact-configurations field-name value) + #~(string-append #$@@(map (cut serialize-configuration <> + contact-configuration-fields) + value))) + +(define (serialize-contacts-list-configuration configuration) + (mixed-text-file + "contactrc" + #~(string-append "[Owner]\n" + #$(serialize-configuration + configuration contacts-list-configuration-fields)))) + +(define-maybe integer) +(define-maybe string) + +(define-configuration contact-configuration + (name + (string) + "The name of the contact." + serialize-contact-name) + (phone-number + (maybe-integer 'disabled) + "The person's phone number.") + (email + (maybe-string 'disabled) + "The person's email address.") + (married? + (boolean) + "Whether the person is married.")) + +(define-configuration contacts-list-configuration + (name + (string) + "The name of the owner of this contact list.") + (email + (string) + "The owner's email address.") + (contacts + (list-of-contact-configurations '()) + "A list of @@code@{contact-configuation@} records which contain +information about all your contacts.")) +@end lisp + +A contacts list configuration could then be created like this: + +@lisp +(define my-contacts + (contacts-list-configuration + (name "Alice") + (email "alice@@example.org") + (contacts + (list (contact-configuration + (name "Bob") + (phone-number 1234) + (email "bob@@gnu.org") + (married? #f)) + (contact-configuration + (name "Charlie") + (phone-number 0000) + (married? #t)))))) +@end lisp + +After serializing the configuration to disk, the resulting file would +look like this: + +@example +[owner] +name =3D Alice +email =3D alice@@example.org + +[Bob] +phone-number =3D 1234 +email =3D bob@@gnu.org +is-married =3D false + +[Charlie] +phone-number =3D 0 +is-married =3D true +@end example + + @node Home Configuration @chapter Home Configuration @cindex home configuration base-commit: 6061540e30269934dae3395ab9fc1b905a414247 --=20 2.33.1 From unknown Wed Sep 24 05:11:10 2025 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] (No Subject) Resent-From: Attila Lendvai Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 22 Dec 2021 10:51:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: "52600@debbugs.gnu.org" <52600@debbugs.gnu.org> Reply-To: Attila Lendvai Received: via spool by 52600-submit@debbugs.gnu.org id=B52600.164017021831963 (code B ref 52600); Wed, 22 Dec 2021 10:51:02 +0000 Received: (at 52600) by debbugs.gnu.org; 22 Dec 2021 10:50:18 +0000 Received: from localhost ([127.0.0.1]:56904 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mzzCL-0008JT-LW for submit@debbugs.gnu.org; Wed, 22 Dec 2021 05:50:18 -0500 Received: from mail-4323.proton.ch ([185.70.43.23]:42527) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mzzCJ-0008J7-1q for 52600@debbugs.gnu.org; Wed, 22 Dec 2021 05:50:17 -0500 Date: Wed, 22 Dec 2021 10:50:06 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lendvai.name; s=protonmail3; t=1640170207; bh=q6BVlZlQZwA3mbA/SJmDlyv4srW57qE+jBhEdfHuBcc=; h=Date:To:From:Reply-To:Subject:Message-ID:In-Reply-To:References: From:To:Cc; b=g4Uncgm5uFPkwK1V8jnkx7isD3Rpkt357t+sl/+Zf4K7mEdoa/Z019B0VZSCSWNbb HxgWkIPN8dLi/baRTYTgKtXloQ+Ah/YibngaLsyTmTPp6+quRV+zuEP4cgS/ktyXYW IhuZTsEtPbKHmyX2RdWaE5ywOT81CMrZhK/lgbLuGS4R/DukUC0DCDw1OenLHdahN9 ODO4W4ESy/F8heYSUcUoGU4dP4vS+ZbUxt7//XpdIKQGRQUqktPi1kFda3JJt3dF61 XY2N9F7EE86he/RFBuVykBqY1kE1r+60xFki7g2pn/au6rlYUbO2kDCAiiED+n9lZD WNrnr6xR40p1g== From: Attila Lendvai Message-ID: In-Reply-To: References: MIME-Version: 1.0 Content-Type: multipart/alternative; boundary="b1_FEfLZSri4TrEqGXmvHQOSok5Gdxlj7FvgKI3tmCJ3D8" X-Spam-Status: No, score=-1.2 required=10.0 tests=ALL_TRUSTED,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,HTML_MESSAGE shortcircuit=no autolearn=disabled version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on mailout.protonmail.ch X-Spam-Score: 2.0 (++) 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: typos: > +A clause can have one the following forms 'of' missing. Content analysis details: (2.0 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 2.0 SLIGHTLY_BAD_SUBJECT Subject contains something slightly spammy -0.0 RCVD_IN_MSPIKE_H3 RBL: Good reputation (+3) [185.70.43.23 listed in wl.mailspike.net] -0.0 SPF_PASS SPF: sender matches SPF record 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.0 HTML_MESSAGE BODY: HTML included in message -0.0 RCVD_IN_MSPIKE_WL Mailspike good senders X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) This is a multi-part message in MIME format. --b1_FEfLZSri4TrEqGXmvHQOSok5Gdxlj7FvgKI3tmCJ3D8 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: base64 dHlwb3M6Cgo+ICtBIGNsYXVzZSBjYW4gaGF2ZSBvbmUgdGhlIGZvbGxvd2luZyBmb3JtcwoKJ29m JyBtaXNzaW5nLgoKPiB0byBnZW5lcmF0ZSBkb2N1bWVudGF0aW9uIGZvciBhbmQgY29uZmlndXJh dGlvbiByZWNvcmRzCgpleHRyYSAnYW5kJy4KCi0tLS0tLS0tLS0tLS0tLQoKYXMgZm9yIHNvbWUg aGlnaGVyIGxldmVsIGZlZWRiYWNrOgoKaSBoYXZlIGp1c3QgZmluaXNoZWQgbXkgZmlyc3QgR3Vp eCBzZXJ2aWNlLCBhIHJhdGhlciBjb21wbGV4IG9uZS4gYmFzZWQgb24gdGhlIGV4YW1wbGVzLCBh bmQgb24gdGhlIGNvbmZpZyBjb2RlYmFzZSBpdHNlbGYsIGkgaGFkIHVzZWQgZGVmaW5lLWNvbmZp Z3VyYXRpb24sIGFuZCBpIGhhZCBlbmNvdW50ZXJlZCBhIHN1cnByaXNlIFdSVCB1bmRlZmluZWQg dmFsdWVzIGFuZCBtYXliZS0gdHlwZXMgKG9ubHkgYWZ0ZXIgdGhhdCBoYXZlIGkgZm91bmQgdGhp cyBkb2N1bWVudGF0aW9uKS4KCj4gZGVmYXVsdC12YWx1ZSBpcyB0aGUgZGVmYXVsdCB2YWx1ZSBj b3JyZXNwb25kaW5nIHRvIHRoZSBmaWVsZDsgaWYKPiBub25lIGlzIHNwZWNpZmllZCwgdGhlIHVz ZXIgaXMgZm9yY2VkIHRvIHByb3ZpZGUgYSB2YWx1ZSB3aGVuIGNyZWF0aW5nCj4gYW4gb2JqZWN0 IG9mIHRoZSByZWNvcmQgdHlwZS4KCmkgd2FzIGV4cGVjdGluZyBpdCB0byBiZSBwb3NzaWJsZSB0 byBoYXZlIGEgZmllbGQgbGlrZToKCihmb28KKG1heWJlLWludGVnZXI/KSkKCmFuZCBpdHMgYmVo YXZpb3Igd291bGQgYmUgdG8gaG9sZCBhbiB1bmRvY3VtZW50ZWQgdmFsdWUgYnkgZGVmYXVsdCwg dGhhdCB0aGUgc2VydmljZSBpbXBsZW1lbnRhdGlvbnMgbmVlZCB0byBjaGVjayBmb3IgdXNpbmcg YSBwdWJsaWMgcHJlZGljYXRlIGZ1bmN0aW9uLiAod2VsbCwgc2hvcnQgb2YgcmVpbXBsZW1lbnRp bmcgYSBmdWxsLWZsZWRnZWQgb2JqZWN0IHN5c3RlbSB3aXRoIGZpZWxkIGFjY2Vzc29yIGFic3Ry YWN0aW9ucywgaS5lLiBzb21ldGhpbmcgbGlrZSBCT1VORFAgaW4gY29tbW9uIGxpc3ApLgoKc29t ZSBvZiB0aGUgY29uZmlnIHZhbHVlcyBpbiBteSBzZXJ2aWNlIGNhbiBjb25kaXRpb25hbGx5IGRl cml2ZSBpdHMgZGVmYXVsdCB2YWx1ZSBiYXNlZCBvbiB0aGUgdmFsdWUgb2Ygb3RoZXIgZmllbGRz LiBpIG5lZWQgdG8gYmUgYWJsZSB0byBkaWZmZXJlbnRpYXRlIGJldHdlZW4gdW5kZWZpbmVkIG9y IHVzZXIgcHJvdmlkZWQgZmllbGQgdmFsdWVzIChpLmUuIGNvbXBsZXRlbHkgaW5kZXBlbmRlbnQg b2YgYW55dGhpbmcgcmVsYXRlZCB0byBzZXJpYWxpemF0aW9uKS4KCnRoZSByZWFzb24gaSBkb24n dCByZWNvbW1lbmQgdGhlIHVzZSBvZiAndW5kZWZpbmVkIGlzIGZpZWxkcyBsaWtlIHRoaXMgdGhh dCB3b3VsZCB3cm9uZ2x5IGJlIGNvbnNpZGVyZWQgdmFsaWQgd2hlbiBubyB2YWx1ZSBpcyBwcm92 aWRlZDoKCihmb28KKHN5bWJvbD8pKQoKPiBTb21ldGltZXMgYSBmaWVsZCBzaG91bGQgbm90IGJl IHNlcmlhbGl6ZWQgaWYgdGhlIHVzZXIgZG9lc27igJl0IHNwZWNpZnkgYQo+IHZhbHVlLiBUbyBh Y2hpZXZlIHRoaXMsIHlvdSBjYW4gdXNlIHRoZSBAY29kZXtkZWZpbmUtbWF5YmV9IG1hY3JvIHRv Cj4gZGVmaW5lIGEgYGBtYXliZSB0eXBlJyc7IGlmIHRoZSB2YWx1ZSBvZiBhIG1heWJlIHR5cGUg aXMgc2V0IHRvIHRoZQo+IEBjb2Rle2Rpc2FibGVkfSwgaXQgd2lsbCBub3QgYmUgc2VyaWFsaXpl ZC4KCnRoZSB1c2Ugb2YgJ2Rpc2FibGVkIGhlcmUgd2FzIHZlcnkgY29uZnVzaW5nIGJlY2F1c2Ug Y29uZmlndXJhdGlvbiBvYmplY3RzIGFyZSB0eXBpY2FsbHkgZnVsbCBvZiBib29sZWFuIGZpZWxk cy4uLiBpcyAnZGlzYWJsZWQgYSB2YWxpZCBhcHAgdmFsdWUsIG9yIHBhcnQgb2YgdGhlIGd1aXgg QVBJPyBjb25mdXNpbmcgdG8gdGhlIHBvaW50IHRoYXQgaSBoYXZlIGNvbmZpZGVudGx5IHJlcG9y dGVkIGl0IGFzIGEgImJ1ZyIgb24gI2d1aXggaW4gdGhlIG1heWJlLSBpbXBsZW1lbnRhdGlvbiB0 byB1c2UgJ2Rpc2FibGVkIGluc3RlYWQgb2YgJ3VuZGVmaW5lZC4KCm1heWJlIHdlIHNob3VsZCB1 c2UgZ3VpbGUncyAqdW5kZWZpbmVkKiwgYW5kIHVuZGVmaW5lZD8gcHJlZGljYXRlICh3aGljaCBp cyBzYWRseSBhIG1hY3JvKS4gb3IgcmVleHBvcnQgYW4gdW5kZWZpbmVkPyBmdW5jdGlvbiwgYW5k IHNoYWRvdyBndWlsZSdzIG1hY3JvPyBpdCdzIG1lc3N5LCBhbmQgZ3VpbGUgc3BlY2lmaWMuCgpv ciBtYXliZSB3ZSBjb3VsZCB1c2UgYSBoZWFwIG9iamVjdCBvZiBhbiB1bnVzdWFsL3ByaXZhdGUg dHlwZSBpbiBhIGdsb2JhbCBwcml2YXRlIHZhcmlhYmxlIHRvIHJlcHJlc2VudCB1bmRlZmluZWQg ZmllbGQgdmFsdWVzLCBhbmQgYWRkIGEgcHVibGljIHByZWRpY2F0ZSB0byB0ZXN0IGZvciBpdC4g dXNpbmcgYSBjb25zIGNlbGwgZm9yIHRoaXMgaXMgdGVtcHRpbmcsIGJ1dCBpdCB3b3VsZCBsZWFr IGltcGxlbWVudGF0aW9uIGRldGFpbHMgZm9yIGZpZWxkcyBvZiB0eXBlIGNvbnM/LiBpJ20gbmV3 IHRvIHNjaGVtZSwgYnV0IHRoZSBiZXN0IGNhbmRpZGF0ZSBpcyBtYXliZSBhIHByaXZhdGUgZHVt bXkgcmVjb3JkIGluc3RhbmNlPwoKaSdkIGFkZCBhIGNvbmZpZ3VyYXRpb24tdW5kZWZpbmVkLXZh bHVlPyBwcmVkaWNhdGUsIGFuZCBhbHNvIGFkZCBhIGNvbmZpZ3VyYXRpb24tZGVmaW5lZC12YWx1 ZT8gd2hvc2Ugc2VtYW50aWNzIGlzIHRvIHJldHVybiB0aGUgdmFsdWUgaXRzZWxmLCBvciAjZmFs c2Ugd2hlbiB1bmRlZmluZWQuIGl0IGNvbWVzIGhhbmR5IGluIChvciAoZGVmaW5lZC12YWx1ZT8g Zm9vKSA0MikgcGF0dGVybnMgZm9yIG5vbi1ib29sZWFuIGZpZWxkcy4KCmluIGZhY3QsIGkgaGFk IHRoZXNlIHR3byBpbiBteSBzZXJ2aWNlIGltcGwsIGJlZm9yZSByZWFkaW5nL3dyaXRpbmcgYW55 IG9mIHRoaXM6CgooZGVmaW5lIChkZWZpbmVkLXZhbHVlPyB4KQooaWYgKGVxPyB4ICd1bmRlZmlu ZWQpICNmYWxzZSB4KSkKCihkZWZpbmUgKHVuZGVmaW5lZC12YWx1ZT8geCkKKGVxPyB4ICd1bmRl ZmluZWQpKQoKdGhlbiB0aGUgcXVlc3Rpb24gYXJpc2VzOiBkbyB3ZSB3YW50IHRvIGRpZmZlcmVu dGlhdGUgYmV0d2VlbiB0aGUgY2FzZXMgd2hlbiB0aGUgZmllbGQgdmFsdWUgY29tZXMgZnJvbSBh IGRlZmF1bHQgZm9ybSwgYW5kIHdoZW4gaXQgaXMgc2V0IGJ5IHRoZSB1c2VyIChlLmcuIGF0IG9i amVjdCBjb25zdHJ1Y3Rpb24gdGltZSk/IGlmIHNvLCB0aGVuIG9uZSB3ZWxsLWtub3duIHZhbHVl IGFzIGEgbWFya2VyIGlzIG5vdCBlbm91Z2gsIGJ1dCBpIGRvbid0IHRoaW5rIGl0J3Mgd29ydGgg dGhlIGFkZGl0aW9uYWwgY29tcGxleGl0eS4gcGVvcGxlIHdpdGggcmFyZSwgY29tcGxleCB1c2Ut Y2FzZXMgY2FuIGFsd2F5cyByZXNvcnQgdG8gZGVmaW5lLXJlY29yZCouCgotLS0tLS0tLS0tLS0t LS0tLS0KCmFub3RoZXIgdGhpbmcgdGhhdCBoYXMgaW5pdGlhbGx5IG1pc2xlZCBtZSB3YXMgdGhl IHdvcmQgJ3NlcmlhbGl6ZSc6IGkgZG9uJ3QgaGF2ZSBhIGJldHRlciBzdWdnZXN0aW9uLCBidXQg aSBoYXZlIGFzc29jaWF0ZWQgaXQgdG8gYSBtb3JlIGZvcm1hbCBzZXJpYWxpemUvZGVzZXJpYWxp emUgcHJvdG9jb2wsIGFzIG9wcG9zZWQgdG8gdHVybmluZyBzY2hlbWUgb2JqZWN0cyBpbnRvIHZh cmlvdXMgZGlmZmVyZW50IGNvbmZpZ3VyYXRpb24gZmlsZSBmb3JtYXRzIHRoYXQgYXJlIG5hdGl2 ZSBmb3IgdGhlIHRhcmdldCBiaW5hcnkuCgptYXliZSBpdCdzIHdvcnRoIGhpbnRpbmcgYXQgaW4g dGhlIGRvY3VtZW50YXRpb24gd2hlcmUgc2VyaWFsaXphdGlvbiBpcyBmaXJzdCBtZW50aW9uZWQu CgotLS0tLS0tLS0tLS0tLS0tLS0KCmlmIHRoZSBBUEkgb2YgdmFsaWRhdGUtY29uZmlndXJhdGlv biBpcyB0byByYWlzZSBlcnJvcnMsIHRoZW4gbWF5YmUgaXQgY291bGQgcmV0dXJuIHRoZSBjb25m aWcgb2JqZWN0IGlmIGV2ZXJ5dGhpbmcgaXMgZmluZS4gdGhhdCBjYW4gc2ltcGxpZnkgdGhlIGNv ZGUgYXQgdGhlIGNhbGwgc2l0ZS4KCkhUSCwKCi0gYXR0aWxhClBHUDogNUQ1RiA0NUM3IERGQ0Qg MEEzOQ== --b1_FEfLZSri4TrEqGXmvHQOSok5Gdxlj7FvgKI3tmCJ3D8 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: base64 PGRpdj48ZGl2PiB0eXBvczo8YnI+PC9kaXY+PC9kaXY+PGRpdiBjbGFzcz0icHJvdG9ubWFpbF9x dW90ZSI+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij48 YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7 Ij48YnI+PC9kaXY+PGJsb2NrcXVvdGU+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBm b250LXNpemU6IDE0cHg7Ij4rQSBjbGF1c2UgY2FuIGhhdmUgb25lIHRoZSBmb2xsb3dpbmcgZm9y bXM8YnI+PC9kaXY+PC9ibG9ja3F1b3RlPjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsg Zm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlh bDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBh cmlhbDsgZm9udC1zaXplOiAxNHB4OyI+J29mJyBtaXNzaW5nLjxicj48L2Rpdj48ZGl2IHN0eWxl PSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPjxicj48L2Rpdj48ZGl2IHN0 eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPjxicj48L2Rpdj48Ymxv Y2txdW90ZT48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsi PnRvIGdlbmVyYXRlIGRvY3VtZW50YXRpb24gZm9yIGFuZCBjb25maWd1cmF0aW9uIHJlY29yZHM8 YnI+PC9kaXY+PC9ibG9ja3F1b3RlPjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9u dC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsg Zm9udC1zaXplOiAxNHB4OyI+ZXh0cmEgJ2FuZCcuPGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQt ZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZv bnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+LS0tLS0tLS0tLS0tLS0tPGJyPjwv ZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+PGJy PjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+ YXMgZm9yIHNvbWUgaGlnaGVyIGxldmVsIGZlZWRiYWNrOjxicj48L2Rpdj48ZGl2IHN0eWxlPSJm b250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPjxicj48L2Rpdj48ZGl2IHN0eWxl PSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPmkgaGF2ZSBqdXN0IGZpbmlz aGVkIG15IGZpcnN0IEd1aXggc2VydmljZSwgYSByYXRoZXIgY29tcGxleCBvbmUuIGJhc2VkIG9u IHRoZSBleGFtcGxlcywgYW5kIG9uIHRoZSBjb25maWcgY29kZWJhc2UgaXRzZWxmLCBpIGhhZCB1 c2VkIGRlZmluZS1jb25maWd1cmF0aW9uLCBhbmQgaSBoYWQgZW5jb3VudGVyZWQgYSBzdXJwcmlz ZSBXUlQgdW5kZWZpbmVkIHZhbHVlcyBhbmQgbWF5YmUtIHR5cGVzIChvbmx5IGFmdGVyIHRoYXQg aGF2ZSBpIGZvdW5kIHRoaXMgZG9jdW1lbnRhdGlvbikuPGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZv bnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9 ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxibG9ja3F1 b3RlPjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+ZGVm YXVsdC12YWx1ZSBpcyB0aGUgZGVmYXVsdCB2YWx1ZSBjb3JyZXNwb25kaW5nIHRvIHRoZSBmaWVs ZDsgaWY8YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6 IDE0cHg7Ij5ub25lIGlzIHNwZWNpZmllZCwgdGhlIHVzZXIgaXMgZm9yY2VkIHRvIHByb3ZpZGUg YSB2YWx1ZSB3aGVuIGNyZWF0aW5nPGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBh cmlhbDsgZm9udC1zaXplOiAxNHB4OyI+YW4gb2JqZWN0IG9mIHRoZSByZWNvcmQgdHlwZS48YnI+ PC9kaXY+PC9ibG9ja3F1b3RlPjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1z aXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9u dC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsg Zm9udC1zaXplOiAxNHB4OyI+aSB3YXMgZXhwZWN0aW5nIGl0IHRvIGJlIHBvc3NpYmxlIHRvIGhh dmUgYSBmaWVsZCBsaWtlOjxicj48L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7 IGZvbnQtc2l6ZTogMTRweDsiPjxicj48L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJp YWw7IGZvbnQtc2l6ZTogMTRweDsiPihmb288YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1p bHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij4mbmJzcDsgKG1heWJlLWludGVnZXI/KSk8YnI+ PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij48 YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7 Ij5hbmQgaXRzIGJlaGF2aW9yIHdvdWxkIGJlIHRvIGhvbGQgYW4gdW5kb2N1bWVudGVkIHZhbHVl IGJ5IGRlZmF1bHQsIHRoYXQgdGhlIHNlcnZpY2UgaW1wbGVtZW50YXRpb25zIG5lZWQgdG8gY2hl Y2sgZm9yIHVzaW5nIGEgcHVibGljIHByZWRpY2F0ZSBmdW5jdGlvbi4gKHdlbGwsIHNob3J0IG9m IHJlaW1wbGVtZW50aW5nIGEgZnVsbC1mbGVkZ2VkIG9iamVjdCBzeXN0ZW0gd2l0aCBmaWVsZCBh Y2Nlc3NvciBhYnN0cmFjdGlvbnMsIGkuZS4gc29tZXRoaW5nIGxpa2UgQk9VTkRQIGluIGNvbW1v biBsaXNwKS48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNp emU6IDE0cHg7Ij48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250 LXNpemU6IDE0cHg7Ij5zb21lIG9mIHRoZSBjb25maWcgdmFsdWVzIGluIG15IHNlcnZpY2UgY2Fu IGNvbmRpdGlvbmFsbHkgZGVyaXZlIGl0cyBkZWZhdWx0IHZhbHVlIGJhc2VkIG9uIHRoZSB2YWx1 ZSBvZiBvdGhlciBmaWVsZHMuIGkgbmVlZCB0byBiZSBhYmxlIHRvIGRpZmZlcmVudGlhdGUgYmV0 d2VlbiB1bmRlZmluZWQgb3IgdXNlciBwcm92aWRlZCBmaWVsZCB2YWx1ZXMgKGkuZS4gY29tcGxl dGVseSBpbmRlcGVuZGVudCBvZiBhbnl0aGluZyByZWxhdGVkIHRvIHNlcmlhbGl6YXRpb24pLjxi cj48L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsi Pjxicj48L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRw eDsiPjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+dGhl IHJlYXNvbiBpIGRvbid0IHJlY29tbWVuZCB0aGUgdXNlIG9mICd1bmRlZmluZWQgaXMgZmllbGRz IGxpa2UgdGhpcyB0aGF0IHdvdWxkIHdyb25nbHkgYmUgY29uc2lkZXJlZCB2YWxpZCB3aGVuIG5v IHZhbHVlIGlzIHByb3ZpZGVkOjxicj48L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJp YWw7IGZvbnQtc2l6ZTogMTRweDsiPjxicj48L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTog YXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPihmb288YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1m YW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij4mbmJzcDsgKHN5bWJvbD8pKTxicj48L2Rp dj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPjxicj48 L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPjxi cj48L2Rpdj48L2Rpdj48YmxvY2txdW90ZT48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7 IGZvbnQtc2l6ZTogMTRweDsiPlNvbWV0aW1lcyBhIGZpZWxkIHNob3VsZCBub3QgYmUgc2VyaWFs aXplZCBpZiB0aGUgdXNlciBkb2VzbuKAmXQgc3BlY2lmeSBhPGJyPjwvZGl2PjxkaXYgc3R5bGU9 ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+dmFsdWUuJm5ic3A7IFRvIGFj aGlldmUgdGhpcywgeW91IGNhbiB1c2UgdGhlIEBjb2Rle2RlZmluZS1tYXliZX0gbWFjcm8gdG88 YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7 Ij5kZWZpbmUgYSBgYG1heWJlIHR5cGUnJzsgaWYgdGhlIHZhbHVlIG9mIGEgbWF5YmUgdHlwZSBp cyBzZXQgdG8gdGhlPGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9u dC1zaXplOiAxNHB4OyI+QGNvZGV7ZGlzYWJsZWR9LCBpdCB3aWxsIG5vdCBiZSBzZXJpYWxpemVk Ljxicj48L2Rpdj48L2Jsb2NrcXVvdGU+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBm b250LXNpemU6IDE0cHg7Ij48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFs OyBmb250LXNpemU6IDE0cHg7Ij48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFy aWFsOyBmb250LXNpemU6IDE0cHg7Ij50aGUgdXNlIG9mICdkaXNhYmxlZCBoZXJlIHdhcyB2ZXJ5 IGNvbmZ1c2luZyBiZWNhdXNlIGNvbmZpZ3VyYXRpb24gb2JqZWN0cyBhcmUgdHlwaWNhbGx5IGZ1 bGwgb2YgYm9vbGVhbiBmaWVsZHMuLi4gaXMgJ2Rpc2FibGVkIGEgdmFsaWQgYXBwIHZhbHVlLCBv ciBwYXJ0IG9mIHRoZSBndWl4IEFQST8gY29uZnVzaW5nIHRvIHRoZSBwb2ludCB0aGF0IGkgaGF2 ZSBjb25maWRlbnRseSByZXBvcnRlZCBpdCBhcyBhICJidWciIG9uICNndWl4IGluIHRoZSBtYXli ZS0gaW1wbGVtZW50YXRpb24gdG8gdXNlICdkaXNhYmxlZCBpbnN0ZWFkIG9mICd1bmRlZmluZWQu PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4 OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAx NHB4OyI+bWF5YmUgd2Ugc2hvdWxkIHVzZSBndWlsZSdzICp1bmRlZmluZWQqLCBhbmQgdW5kZWZp bmVkPyBwcmVkaWNhdGUgKHdoaWNoIGlzIHNhZGx5IGEgbWFjcm8pLiBvciByZWV4cG9ydCBhbiB1 bmRlZmluZWQ/IGZ1bmN0aW9uLCBhbmQgc2hhZG93IGd1aWxlJ3MgbWFjcm8/IGl0J3MgbWVzc3ks IGFuZCBndWlsZSBzcGVjaWZpYy48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFy aWFsOyBmb250LXNpemU6IDE0cHg7Ij48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZv bnQtc2l6ZTogMTRweDsiPjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXpl OiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1z aXplOiAxNHB4OyI+b3IgbWF5YmUgd2UgY291bGQgdXNlIGEgaGVhcCBvYmplY3Qgb2YgYW4gdW51 c3VhbC9wcml2YXRlIHR5cGUgaW4gYSBnbG9iYWwgcHJpdmF0ZSB2YXJpYWJsZSB0byByZXByZXNl bnQgdW5kZWZpbmVkIGZpZWxkIHZhbHVlcywgYW5kIGFkZCBhIHB1YmxpYyBwcmVkaWNhdGUgdG8g dGVzdCBmb3IgaXQuIHVzaW5nIGEgY29ucyBjZWxsIGZvciB0aGlzIGlzIHRlbXB0aW5nLCBidXQg aXQgd291bGQgbGVhayBpbXBsZW1lbnRhdGlvbiBkZXRhaWxzIGZvciBmaWVsZHMgb2YgdHlwZSBj b25zPy4gaSdtIG5ldyB0byBzY2hlbWUsIGJ1dCB0aGUgYmVzdCBjYW5kaWRhdGUgaXMgbWF5YmUg YSBwcml2YXRlIGR1bW15IHJlY29yZCBpbnN0YW5jZT88YnI+PC9kaXY+PC9kaXY+PGRpdj48YnI+ PC9kaXY+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0 cHg7Ij48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPmkn ZCBhZGQgYSBjb25maWd1cmF0aW9uLXVuZGVmaW5lZC12YWx1ZT8gcHJlZGljYXRlLCBhbmQgYWxz byBhZGQgYSBjb25maWd1cmF0aW9uLWRlZmluZWQtdmFsdWU/IHdob3NlIHNlbWFudGljcyBpcyB0 byByZXR1cm4gdGhlIHZhbHVlIGl0c2VsZiwgb3IgI2ZhbHNlIHdoZW4gdW5kZWZpbmVkLiBpdCBj b21lcyBoYW5keSBpbiAob3IgKGRlZmluZWQtdmFsdWU/IGZvbykgNDIpIHBhdHRlcm5zIGZvciBu b24tYm9vbGVhbiBmaWVsZHMuPGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlh bDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXY+aW4gZmFjdCwgaSBoYWQgdGhlc2Ug dHdvIGluIG15IHNlcnZpY2UgaW1wbCwgYmVmb3JlIHJlYWRpbmcvd3JpdGluZyBhbnkgb2YgdGhp czo8YnI+PC9kaXY+PGRpdj48YnI+PC9kaXY+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6 IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij4oZGVmaW5lIChkZWZpbmVkLXZhbHVlPyB4KTxicj48 L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7IGZvbnQtc2l6ZTogMTRweDsiPiZu YnNwOyAoaWYgKGVxPyB4ICd1bmRlZmluZWQpICNmYWxzZSB4KSk8YnI+PC9kaXY+PGRpdiBzdHls ZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij48YnI+PC9kaXY+PGRpdiBz dHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij4oZGVmaW5lICh1bmRl ZmluZWQtdmFsdWU/IHgpPGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsg Zm9udC1zaXplOiAxNHB4OyI+Jm5ic3A7IChlcT8geCAndW5kZWZpbmVkKSk8YnI+PC9kaXY+PGRp diBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij48YnI+PC9kaXY+ PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij50aGVuIHRo ZSBxdWVzdGlvbiBhcmlzZXM6IGRvIHdlIHdhbnQgdG8gZGlmZmVyZW50aWF0ZSBiZXR3ZWVuIHRo ZSBjYXNlcyB3aGVuIHRoZSBmaWVsZCB2YWx1ZSBjb21lcyBmcm9tIGEgZGVmYXVsdCBmb3JtLCBh bmQgd2hlbiBpdCBpcyBzZXQgYnkgdGhlIHVzZXIgKGUuZy4gYXQgb2JqZWN0IGNvbnN0cnVjdGlv biB0aW1lKT8gaWYgc28sIHRoZW4gb25lIHdlbGwta25vd24gdmFsdWUgYXMgYSBtYXJrZXIgaXMg bm90IGVub3VnaCwgYnV0IGkgZG9uJ3QgdGhpbmsgaXQncyB3b3J0aCB0aGUgYWRkaXRpb25hbCBj b21wbGV4aXR5LiBwZW9wbGUgd2l0aCByYXJlLCBjb21wbGV4IHVzZS1jYXNlcyBjYW4gYWx3YXlz IHJlc29ydCB0byBkZWZpbmUtcmVjb3JkKi48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1p bHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1m YW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij4tLS0tLS0tLS0tLS0tLS0tLS08YnI+PC9k aXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij48YnI+ PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij5h bm90aGVyIHRoaW5nIHRoYXQgaGFzIGluaXRpYWxseSBtaXNsZWQgbWUgd2FzIHRoZSB3b3JkICdz ZXJpYWxpemUnOiBpIGRvbid0IGhhdmUgYSBiZXR0ZXIgc3VnZ2VzdGlvbiwgYnV0IGkgaGF2ZSBh c3NvY2lhdGVkIGl0IHRvIGEgbW9yZSBmb3JtYWwgc2VyaWFsaXplL2Rlc2VyaWFsaXplIHByb3Rv Y29sLCBhcyBvcHBvc2VkIHRvIHR1cm5pbmcgc2NoZW1lIG9iamVjdHMgaW50byB2YXJpb3VzIGRp ZmZlcmVudCBjb25maWd1cmF0aW9uIGZpbGUgZm9ybWF0cyB0aGF0IGFyZSBuYXRpdmUgZm9yIHRo ZSB0YXJnZXQgYmluYXJ5Ljxicj48L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJpYWw7 IGZvbnQtc2l6ZTogMTRweDsiPjxicj48L2Rpdj48ZGl2IHN0eWxlPSJmb250LWZhbWlseTogYXJp YWw7IGZvbnQtc2l6ZTogMTRweDsiPm1heWJlIGl0J3Mgd29ydGggaGludGluZyBhdCBpbiB0aGUg ZG9jdW1lbnRhdGlvbiB3aGVyZSBzZXJpYWxpemF0aW9uIGlzIGZpcnN0IG1lbnRpb25lZC48YnI+ PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij48 YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7 Ij4tLS0tLS0tLS0tLS0tLS0tLS08YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6IGFy aWFsOyBmb250LXNpemU6IDE0cHg7Ij48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1mYW1pbHk6 IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij5pZiB0aGUgQVBJIG9mJm5ic3A7dmFsaWRhdGUtY29u ZmlndXJhdGlvbiBpcyB0byByYWlzZSBlcnJvcnMsIHRoZW4gbWF5YmUgaXQgY291bGQgcmV0dXJu IHRoZSBjb25maWcgb2JqZWN0IGlmIGV2ZXJ5dGhpbmcgaXMgZmluZS4gdGhhdCBjYW4gc2ltcGxp ZnkgdGhlIGNvZGUgYXQgdGhlIGNhbGwgc2l0ZS48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9udC1m YW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij48YnI+PC9kaXY+PGRpdiBzdHlsZT0iZm9u dC1mYW1pbHk6IGFyaWFsOyBmb250LXNpemU6IDE0cHg7Ij5IVEgsPGJyPjwvZGl2PjxkaXYgc3R5 bGU9ImZvbnQtZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXY+ PGRpdiBjbGFzcz0icHJvdG9ubWFpbF9zaWduYXR1cmVfYmxvY2siPjxkaXYgY2xhc3M9InByb3Rv bm1haWxfc2lnbmF0dXJlX2Jsb2NrLXVzZXIiPjxkaXY+LSBhdHRpbGE8YnI+PC9kaXY+PGRpdj5Q R1A6Jm5ic3A7NUQ1RiA0NUM3IERGQ0QgMEEzOTxicj48L2Rpdj48L2Rpdj48ZGl2IGNsYXNzPSJw cm90b25tYWlsX3NpZ25hdHVyZV9ibG9jay1wcm90b24gcHJvdG9ubWFpbF9zaWduYXR1cmVfYmxv Y2stZW1wdHkiPjwvZGl2PjwvZGl2PjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBhcmlh bDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQtZmFt aWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2PjxkaXYgc3R5bGU9ImZvbnQt ZmFtaWx5OiBhcmlhbDsgZm9udC1zaXplOiAxNHB4OyI+PGJyPjwvZGl2Pg== --b1_FEfLZSri4TrEqGXmvHQOSok5Gdxlj7FvgKI3tmCJ3D8-- From unknown Wed Sep 24 05:11:10 2025 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration). Resent-From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Wed, 22 Dec 2021 22:15:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Xinglu Chen Cc: Maxim Cournoyer , 52600@debbugs.gnu.org, Andrew Tropin Received: via spool by 52600-submit@debbugs.gnu.org id=B52600.16402112717689 (code B ref 52600); Wed, 22 Dec 2021 22:15:01 +0000 Received: (at 52600) by debbugs.gnu.org; 22 Dec 2021 22:14:31 +0000 Received: from localhost ([127.0.0.1]:59917 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n09sU-0001zs-Dd for submit@debbugs.gnu.org; Wed, 22 Dec 2021 17:14:31 -0500 Received: from hera.aquilenet.fr ([185.233.100.1]:46182) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n09sT-0001zR-3H for 52600@debbugs.gnu.org; Wed, 22 Dec 2021 17:14:29 -0500 Received: from localhost (localhost [127.0.0.1]) by hera.aquilenet.fr (Postfix) with ESMTP id 60CA6329; Wed, 22 Dec 2021 23:14:22 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at aquilenet.fr Received: from hera.aquilenet.fr ([127.0.0.1]) by localhost (hera.aquilenet.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id E4L3q_ls8XRP; Wed, 22 Dec 2021 23:14:21 +0100 (CET) Received: from ribbon (91-160-117-201.subs.proxad.net [91.160.117.201]) by hera.aquilenet.fr (Postfix) with ESMTPSA id 151D4171; Wed, 22 Dec 2021 23:14:20 +0100 (CET) From: Ludovic =?UTF-8?Q?Court=C3=A8s?= References: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> Date: Wed, 22 Dec 2021 23:14:20 +0100 In-Reply-To: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> (Xinglu Chen's message of "Sat, 18 Dec 2021 16:12:38 +0100") Message-ID: <877dbwz3r7.fsf@gnu.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spamd-Bar: + X-Spam-Level: * X-Rspamd-Server: hera Authentication-Results: hera.aquilenet.fr; none X-Rspamd-Queue-Id: 60CA6329 X-Spamd-Result: default: False [1.40 / 15.00]; ARC_NA(0.00)[]; RCVD_VIA_SMTP_AUTH(0.00)[]; FREEMAIL_CC(0.00)[debbugs.gnu.org,gmail.com,trop.in]; FROM_HAS_DN(0.00)[]; RCPT_COUNT_THREE(0.00)[4]; FREEMAIL_ENVRCPT(0.00)[gmail.com]; TO_MATCH_ENVRCPT_ALL(0.00)[]; TAGGED_RCPT(0.00)[]; MIME_GOOD(-0.10)[text/plain]; TO_DN_SOME(0.00)[]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; RCVD_COUNT_TWO(0.00)[2]; RCVD_TLS_ALL(0.00)[]; MID_RHS_MATCH_FROM(0.00)[]; SUSPICIOUS_RECIPS(1.50)[] X-Spam-Score: 3.0 (+++) 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: Hi, Xinglu Chen skribis: > * guix.texi (Complex Configurations): New node. Content analysis details: (3.0 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 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 2.0 (++) 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: Hi, Xinglu Chen skribis: > * guix.texi (Complex Configurations): New node. Content analysis details: (2.0 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 -1.0 MAILING_LIST_MULTI Multiple indicators imply a widely-seen list manager Hi, Xinglu Chen skribis: > * guix.texi (Complex Configurations): New node. Great work! I applied it and fixed typos Attila reported plus =E2=80=9Cbin= dgs=E2=80=9D (instead of =E2=80=9Cbindings=E2=80=9D). > This patch documents the complex beast that is the (gnu services > configuration) module. I only documented the things that existed before > the Guix Home merge, though. There were a lot of things to document, and > I hope that my explanations aren=E2=80=99t too confusing (It took me a wh= ile to > wrap my head around all of this). :-) It looks very clear to me. > What is still missing is some kind of style guide for writing Guix > services: When should one use (gnu services configuration) vs plain > (guix records)? Should we try to create bindings for all config options > or should we provide an =E2=80=9Cescape hatch=E2=80=9D for users? > > I would personally prefer if most (if not all) services were written > using (gnu services configuration), but I don=E2=80=99t really think refa= ctoring > existing services would really be worth it. But that=E2=80=99s another d= iscussion. Yeah. So far the (unwritten) guideline has always been: =E2=80=A2 Have record types that provide bindings for all or most of the available options; =E2=80=A2 Always provide an =E2=80=9Cescape hatch=E2=80=9D so users can i= nsert raw configuration snippets, either because the bindings don=E2=80=99t cover everything, or because they have an existing config file they=E2=80=99d= like to reuse. We should probably write it down somewhere. Maybe we need a new section next to =E2=80=9CPackaging Guidelines=E2=80=9D to discuss system services? As for =E2=80=98define-configuration=E2=80=99 vs. (guix records) vs. SRFI-9= =E2=80=A6 I don=E2=80=99t think we really discussed the issue or agreed on something. For the rather simple services I wrote, I was happy to use plain records and home-made serializers rather than =E2=80=98define-configuration=E2=80= =99. But overall it seems to make more sense to recommend =E2=80=98define-configurat= ion=E2=80=99 unconditionally. I guess it already has serializers for the most common formats, which are all alike, so we should be able to avoid boilerplate. Thoughts? Thanks for substantially improving the manual! Ludo=E2=80=99. From debbugs-submit-bounces@debbugs.gnu.org Wed Dec 22 17:14:37 2021 Received: (at control) by debbugs.gnu.org; 22 Dec 2021 22:14:37 +0000 Received: from localhost ([127.0.0.1]:59920 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n09sb-00020J-38 for submit@debbugs.gnu.org; Wed, 22 Dec 2021 17:14:37 -0500 Received: from hera.aquilenet.fr ([185.233.100.1]:46204) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n09sZ-0001zn-Ch for control@debbugs.gnu.org; Wed, 22 Dec 2021 17:14:35 -0500 Received: from localhost (localhost [127.0.0.1]) by hera.aquilenet.fr (Postfix) with ESMTP id 0C8AC329 for ; Wed, 22 Dec 2021 23:14:30 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at aquilenet.fr Received: from hera.aquilenet.fr ([127.0.0.1]) by localhost (hera.aquilenet.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 0veXks-ux_K3 for ; Wed, 22 Dec 2021 23:14:29 +0100 (CET) Received: from ribbon (91-160-117-201.subs.proxad.net [91.160.117.201]) by hera.aquilenet.fr (Postfix) with ESMTPSA id 842B5171 for ; Wed, 22 Dec 2021 23:14:29 +0100 (CET) Date: Wed, 22 Dec 2021 23:14:29 +0100 Message-Id: <875yrgz3qy.fsf@gnu.org> To: control@debbugs.gnu.org From: =?utf-8?Q?Ludovic_Court=C3=A8s?= Subject: control message for bug #52600 MIME-version: 1.0 Content-type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Spamd-Bar: / Authentication-Results: hera.aquilenet.fr; none X-Rspamd-Server: hera X-Rspamd-Queue-Id: 0C8AC329 X-Spamd-Result: default: False [0.61 / 15.00]; ARC_NA(0.00)[]; RCVD_VIA_SMTP_AUTH(0.00)[]; FROM_HAS_DN(0.00)[]; TO_MATCH_ENVRCPT_ALL(0.00)[]; MIME_GOOD(-0.10)[text/plain]; TO_DN_NONE(0.00)[]; PREVIOUSLY_DELIVERED(0.00)[control@debbugs.gnu.org]; RCPT_COUNT_ONE(0.00)[1]; FROM_EQ_ENVFROM(0.00)[]; MIME_TRACE(0.00)[0:+]; R_MIXED_CHARSET(0.71)[subject]; RCVD_COUNT_TWO(0.00)[2]; RCVD_TLS_ALL(0.00)[]; MID_RHS_MATCH_FROM(0.00)[] X-Spam-Score: 1.0 (+) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.0 (/) close 52600 quit From unknown Wed Sep 24 05:11:10 2025 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration). Resent-From: Xinglu Chen Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Thu, 23 Dec 2021 10:43:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Ludovic =?UTF-8?Q?Court=C3=A8s?= Cc: Attila Lendvai , Maxim Cournoyer , 52600@debbugs.gnu.org, Andrew Tropin Received: via spool by 52600-submit@debbugs.gnu.org id=B52600.164025614826479 (code B ref 52600); Thu, 23 Dec 2021 10:43:02 +0000 Received: (at 52600) by debbugs.gnu.org; 23 Dec 2021 10:42:28 +0000 Received: from localhost ([127.0.0.1]:60504 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n0LYK-0006t0-Ad for submit@debbugs.gnu.org; Thu, 23 Dec 2021 05:42:28 -0500 Received: from h87-96-130-155.cust.a3fiber.se ([87.96.130.155]:50750 helo=mail.yoctocell.xyz) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n0LYI-0006sn-TM for 52600@debbugs.gnu.org; Thu, 23 Dec 2021 05:42:27 -0500 From: Xinglu Chen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yoctocell.xyz; s=mail; t=1640256140; bh=pKk05i/zZKkrVspWOSY0cx1Few3JY4/60xCWKjtXla0=; h=From:To:Cc:Subject:In-Reply-To:References:Date; b=lHkn9dlF+roQ0Af4oU7mZVjYkPnm28lYU/e8+Gi800qo23fV0FggHxfjL6Sb/DhBe uFoZLvKu+crrq+9rwF2U7Gci9x3Vo8V7yPJcFE5vtHF4ySY5sHCXjoBY41snt80vj7 4dcMkHtS+VYvC/iqFfYZYO6gcUAm/klT/7Sj2HHA= In-Reply-To: <877dbwz3r7.fsf@gnu.org> References: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> <877dbwz3r7.fsf@gnu.org> Date: Thu, 23 Dec 2021 11:42:18 +0100 Message-ID: <87ilvfd2lx.fsf@yoctocell.xyz> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" X-Spam-Score: 2.9 (++) 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: Hi, Ludovic schrieb am Mittwoch der 22. Dezember 2021 um 23:14 +01: > Hi, > > Xinglu Chen skribis: > >> * guix.texi (Complex Configurations): New node. > > Great work! I applied it and fixed typos Attila reported plus =?UTF-8?Q?=E2=80=9Cbindgs=E2=80=9D?= > (instead of [...] Content analysis details: (2.9 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 SPF_PASS SPF: sender matches SPF record 2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs [URI: yoctocell.xyz (xyz)] 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.5 FROM_SUSPICIOUS_NTLD From abused NTLD 0.4 RDNS_DYNAMIC Delivered to internal network by host with dynamic-looking rDNS 0.0 PDS_RDNS_DYNAMIC_FP RDNS_DYNAMIC with FP steps X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 2.9 (++) 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: Hi, Ludovic schrieb am Mittwoch der 22. Dezember 2021 um 23:14 +01: > Hi, > > Xinglu Chen skribis: > >> * guix.texi (Complex Configurations): New node. > > Great work! I applied it and fixed typos Attila reported plus =?UTF-8?Q?=E2=80=9Cbindgs=E2=80=9D?= > (instead of [...] Content analysis details: (2.9 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 SPF_PASS SPF: sender matches SPF record 2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs [URI: yoctocell.xyz (xyz)] 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.5 FROM_SUSPICIOUS_NTLD From abused NTLD 0.4 RDNS_DYNAMIC Delivered to internal network by host with dynamic-looking rDNS 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 0.0 PDS_RDNS_DYNAMIC_FP RDNS_DYNAMIC with FP steps --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi, Ludovic schrieb am Mittwoch der 22. Dezember 2021 um 23:14 +01: > Hi, > > Xinglu Chen skribis: > >> * guix.texi (Complex Configurations): New node. > > Great work! I applied it and fixed typos Attila reported plus =E2=80=9Cb= indgs=E2=80=9D > (instead of =E2=80=9Cbindings=E2=80=9D). Great, thanks for taking a look. I didn=E2=80=99t receive any message from Attila though, and there doesn=E2=80=99t seem to be anything on the ML eith= er. I guess he sent it when all the GNU infra was down, but unless he didn=E2= =80=99t Cc me, I don=E2=80=99t see why I wouldn=E2=80=99t receive it. >> This patch documents the complex beast that is the (gnu services >> configuration) module. I only documented the things that existed before >> the Guix Home merge, though. There were a lot of things to document, and >> I hope that my explanations aren=E2=80=99t too confusing (It took me a w= hile to >> wrap my head around all of this). :-) > > It looks very clear to me. Good to know. :-) >> What is still missing is some kind of style guide for writing Guix >> services: When should one use (gnu services configuration) vs plain >> (guix records)? Should we try to create bindings for all config options >> or should we provide an =E2=80=9Cescape hatch=E2=80=9D for users? >> >> I would personally prefer if most (if not all) services were written >> using (gnu services configuration), but I don=E2=80=99t really think ref= actoring >> existing services would really be worth it. But that=E2=80=99s another = discussion. > > Yeah. So far the (unwritten) guideline has always been: > > =E2=80=A2 Have record types that provide bindings for all or most of the > available options; > > =E2=80=A2 Always provide an =E2=80=9Cescape hatch=E2=80=9D so users can= insert raw > configuration snippets, either because the bindings don=E2=80=99t cov= er > everything, or because they have an existing config file they=E2=80= =99d like > to reuse. > > We should probably write it down somewhere. Maybe we need a new section > next to =E2=80=9CPackaging Guidelines=E2=80=9D to discuss system services? That sounds like a good idea; Andrew started to work on something like that[1]. > As for =E2=80=98define-configuration=E2=80=99 vs. (guix records) vs. SRFI= -9=E2=80=A6 I don=E2=80=99t > think we really discussed the issue or agreed on something. > > For the rather simple services I wrote, I was happy to use plain records > and home-made serializers rather than =E2=80=98define-configuration=E2=80= =99. But > overall it seems to make more sense to recommend =E2=80=98define-configur= ation=E2=80=99 > unconditionally. I guess it already has serializers for the most common > formats, which are all alike, so we should be able to avoid > boilerplate. > > Thoughts? Agreed, since =E2=80=98define-configuration=E2=80=99 & friends are now docu= mented, it makes even more sense to use them. > Thanks for substantially improving the manual! You are welcome! :-) [1]: --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJJBAEBCAAzFiEEAVhh4yyK5+SEykIzrPUJmaL7XHkFAmHEUosVHHB1YmxpY0B5 b2N0b2NlbGwueHl6AAoJEKz1CZmi+1x5Rn8P/3cHPPncCAhpBaiOKkg2IYB3YMNz X5OdEEiVMMqA5oxcY2vNX8mxDc/daVsixUFc1cq+H5KKo9SU5Jl1Lh0a8XFEikmP zKZjZbdPA0ohyM4ZI3pKGkFY2s6ZV2YiB5VlMOUuOQmiasvX4z+EHpuZVP+7qhjb No0I3cPOxTvdQP8LUraxAzO6bR5eYFOVLsyqWXTAgWa15l4C7gKOiMZiahaMNLXC h+acznf0O9uBu7O6dlerNQfaV4/MhuvQ6oBLEpYYyWgeT42KUUMnleGfmtalKUFI 1ZTKKjNrX+5GD+pWEra5XcZGhu7GP815ZNwruAOc+SWqIKAv8Af4xMI1xvmVBzWm rztAhNmqnNDY0x0RtcychkQTQzRznR4qTJnpn05uSJFJXUmWTFJldZyOJ4fTAiG7 v+YiesYSCHkTstyv9WsL6l4OV/hmx5Efe/6UuOSM5f42nTEwI5nxhlAi7N4UA1vE LGHPvvy0wRH/NEG3/bsMM16kauiScIUPZj0ukaMxBhwjWKh7hKl/I7h+9seJpylP utR/hME+CfPmU76gu0AQqbvbpCSP7V7XlBRPcJuENlTF9Jso6wocJdpixdpoQFFX yb+7Ld6B1WvMZmuirnKq/S12Xuxza2dV2KenVf+GBaxxwPtVayKkcEd7gIL2FWwH yV0xmGMD4HIkzJQI =So/f -----END PGP SIGNATURE----- --=-=-=-- From unknown Wed Sep 24 05:11:10 2025 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration). Resent-From: Xinglu Chen Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Thu, 23 Dec 2021 12:55:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Attila Lendvai Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , 52600@debbugs.gnu.org, Maxim Cournoyer , Andrew Tropin Received: via spool by 52600-submit@debbugs.gnu.org id=B52600.164026409424256 (code B ref 52600); Thu, 23 Dec 2021 12:55:01 +0000 Received: (at 52600) by debbugs.gnu.org; 23 Dec 2021 12:54:54 +0000 Received: from localhost ([127.0.0.1]:60617 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n0NcT-0006JA-Dw for submit@debbugs.gnu.org; Thu, 23 Dec 2021 07:54:53 -0500 Received: from h87-96-130-155.cust.a3fiber.se ([87.96.130.155]:53322 helo=mail.yoctocell.xyz) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n0NcR-0006Ix-Uk for 52600@debbugs.gnu.org; Thu, 23 Dec 2021 07:54:52 -0500 From: Xinglu Chen DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=yoctocell.xyz; s=mail; t=1640264085; bh=Ews1GYAP2HxNpS5lEWJ0chi/431GT5qIv5SkLu0j3mM=; h=From:To:Cc:Subject:In-Reply-To:References:Date; b=vXW6tHb6fHySjVLDTZptIFlvXG5diP5x7SSl6ShtHmveqF2W/4YQi8W7HE0irQr87 QNNqOza8Sn+NM47rw+iyXlDpgsoNrY9nq1p7/kVnP66lyqziTLDyky68TMMalm/2JU 5jYJ65CzzB19ZFfO+J7QDiwEM5ftPn2lWIT2WnoI= In-Reply-To: References: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> <877dbwz3r7.fsf@gnu.org> <87ilvfd2lx.fsf@yoctocell.xyz> Date: Thu, 23 Dec 2021 13:54:44 +0100 Message-ID: <87a6grcwh7.fsf@yoctocell.xyz> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" X-Spam-Score: 2.9 (++) 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: Attila schrieb am Donnerstag der 23. Dezember 2021 um 11:18 GMT: >> Great, thanks for taking a look. I =?UTF-8?Q?didn=E2=80=99t?= receive any message from >> Attila though, and there =?UTF-8?Q?doesn=E2=80=99t?= seem to be anything on the ML either. >> >> I guess he sent it when all the GNU infra was [...] Content analysis details: (2.9 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 SPF_PASS SPF: sender matches SPF record 2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs [URI: yoctocell.xyz (xyz)] 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.5 FROM_SUSPICIOUS_NTLD From abused NTLD 0.4 RDNS_DYNAMIC Delivered to internal network by host with dynamic-looking rDNS 0.0 PDS_RDNS_DYNAMIC_FP RDNS_DYNAMIC with FP steps X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 2.9 (++) 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: Attila schrieb am Donnerstag der 23. Dezember 2021 um 11:18 GMT: >> Great, thanks for taking a look. I =?UTF-8?Q?didn=E2=80=99t?= receive any message from >> Attila though, and there =?UTF-8?Q?doesn=E2=80=99t?= seem to be anything on the ML either. >> >> I guess he sent it when all the GNU infra was [...] Content analysis details: (2.9 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- -0.0 SPF_PASS SPF: sender matches SPF record 2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs [URI: yoctocell.xyz (xyz)] 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 0.5 FROM_SUSPICIOUS_NTLD From abused NTLD 0.4 RDNS_DYNAMIC Delivered to internal network by host with dynamic-looking rDNS 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 0.0 PDS_RDNS_DYNAMIC_FP RDNS_DYNAMIC with FP steps --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Attila schrieb am Donnerstag der 23. Dezember 2021 um 11:18 GMT: >> Great, thanks for taking a look. I didn=E2=80=99t receive any message fr= om >> Attila though, and there doesn=E2=80=99t seem to be anything on the ML e= ither. >> >> I guess he sent it when all the GNU infra was down, but unless he didn= =E2=80=99t >> Cc me, I don=E2=80=99t see why I wouldn=E2=80=99t receive it. > > yep. since then i have resent it, available at: > > https://issues.guix.gnu.org/52600#1 Oh, I already had it in my archive, but it was missing a subject, and it wasn=E2=80=99t part of any thread, so I didn=E2=80=99t see it. Now to the reply: > as for some higher level feedback: >=20 > i have just finished my first Guix service, a rather complex > one. based on the examples, and on the config codebase itself, i had > used define-configuration, and i had encountered a surprise WRT > undefined values and maybe- types (only after that have i found this > documentation). >=20 > > default-value is the default value corresponding to the field; if > > none is specified, the user is forced to provide a value when creating > > an object of the record type. >=20 > i was expecting it to be possible to have a field like: >=20 > (foo > (maybe-integer?)) A =E2=80=98maybe-=E2=80=99 type doesn=E2=80=99t necessarily have to have a = default value set to =E2=80=98disabled=E2=80=99. The default value of the =E2=80=98foo=E2=80=99= field could just as well be =E2=80=983=E2=80=99 or something. > and its behavior would be to hold an undocumented value by default, > that the service implementations need to check for using a public > predicate function. What do you mean by =E2=80=9Cundocumented value=E2=80=9D? > some of the config values in my service can conditionally derive its > default value based on the value of other fields. I don=E2=80=99t think this is possible with =E2=80=98define-configuration= =E2=80=99 yet. But it would be a nice feature to have. > i need to be able to differentiate between undefined or user provided > field values (i.e. completely independent of anything related to > serialization). Maybe we could change =E2=80=98undefined=E2=80=99 to instead be an exceptio= n, which will raised when the user doesn=E2=80=99t provide anything. > > Sometimes a field should not be serialized if the user doesn=E2=80=99t = specify a > > value. To achieve this, you can use the @code{define-maybe} macro to > > define a ``maybe type''; if the value of a maybe type is set to the > > @code{disabled}, it will not be serialized. >=20 > the use of 'disabled here was very confusing because configuration > objects are typically full of boolean fields... is 'disabled a valid > app value, or part of the guix API? Boolean fields would be specified using Guile booleans, which would then get serialized to whatever syntax the configuration language expects. But you are right that it could be ambigous sometimes. > maybe we should use guile's *undefined*, and undefined? predicate > (which is sadly a macro). or reexport an undefined? function, and > shadow guile's macro? it's messy, and guile specific. I am not familiar with Guile internals, but I think that =E2=80=98#=E2=80=99 is just a thing that the pretty-printer pr= ints. Maybe we could use =E2=80=9Cproper=E2=80=9D Maybe types, like in SRFI-189[1]? [1]: Using > or maybe we could use a heap object of an unusual/private type in a > global private variable to represent undefined field values, and add a > public predicate to test for it. using a cons cell for this is > tempting, but it would leak implementation details for fields of type > cons?. i'm new to scheme, but the best candidate is maybe a private > dummy record instance? But what if a user wants to set a field to =E2=80=98disabled=E2=80=99 (beca= use they don=E2=80=99t want anything to get serialized), then that record would have= to be public. > i'd add a configuration-undefined-value? predicate, and also add a > configuration-defined-value? whose semantics is to return the value > itself, or #false when undefined. it comes handy in (or > (defined-value? foo) 42) patterns for non-boolean fields. But what if the value itself is #f? You wouldn=E2=80=99t be able to distin= guish between the cases where the value is undefined and when the value is #f. > in fact, i had these two in my service impl, before reading/writing > any of this: >=20 > (define (defined-value? x) > (if (eq? x 'undefined) #false x)) >=20 > (define (undefined-value? x) > (eq? x 'undefined)) >=20 > then the question arises: do we want to differentiate between the > cases when the field value comes from a default form, and when it is > set by the user (e.g. at object construction time)? if so, then one > well-known value as a marker is not enough, but i don't think it's > worth the additional complexity. people with rare, complex use-cases > can always resort to define-record*. I don=E2=80=99t really see a use of having that functionality; do you have = any examples when this would be useful to have? > another thing that has initially misled me was the word 'serialize': i > don't have a better suggestion, but i have associated it to a more > formal serialize/deserialize protocol, as opposed to turning scheme > objects into various different configuration file formats that are > native for the target binary. >=20 > maybe it's worth hinting at in the documentation where serialization > is first mentioned. The second paragraph explains this, no? Or do you think it can be improved? =2D-8<---------------cut here---------------start------------->8--- The main utility is the @code{define-configuration} macro, which you will use to define a Scheme record type (@pxref{Record Overview,,, guile, GNU Guile Reference Manual}). The Scheme record will be serialized to a configuration file by using @dfn{serializers}, which are procedures that take some kind of Scheme value and returns a G-expression (@pxref{G-Expressions}), which should, once serialized to the disk, return a string. More details are listed below. =2D-8<---------------cut here---------------end--------------->8--- > if the API of validate-configuration is to raise errors, then maybe it > could return the config object if everything is fine. that can > simplify the code at the call site. That=E2=80=99s probably a good idea. --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQJJBAEBCAAzFiEEAVhh4yyK5+SEykIzrPUJmaL7XHkFAmHEcZQVHHB1YmxpY0B5 b2N0b2NlbGwueHl6AAoJEKz1CZmi+1x5a+EP/3OILpTCVj22h22NP1P5xlhZZP1R /aXn+kKeIV+S6Nu0pmLYNwWhV14o6gzi4X5iJUSvDyULe0AT2BsviUSSlEsnQONL /GQOwBlfJRE4rkfaOD9uxIzalDGYLTCvjnAnJz4sIXKIpxF8rJjESjTzowrNpE2h Yatza/YWDJ/XvyY/r3FdycYOhAbeIGBOI/gfITKoK+bScot4cS84v0GU71VmHsXg NVjMmiUyT5INC/rnNXHHKaN9n53SP86U/jndiubXDn65RLG4Ue/GTUAik4FxK9i+ uTqksbV0H7HBFsNtBi58A6XpasdnbEUt62kUZ++5gJgL74mMIXedejJ1MaQ3iOEj 4b6Xzg9fBNUGZXyaVVdQSWz4KK6UHS1KLxbUBE30R7iR37dgUiwDvZi1/rt+CZCb 9ulTod7YqxfKb5KTCNFZfjrPKHLh8o6Od629TP5BIuqXlJTY1nmjSWGRm17NcKXm gSTqu6URtXtvi1u1BrREumzUWoSyCcp6kl4AFKsAiCpEERMdVNlObp6FbhzkYgsO 8itLxEd3oeKSsbcNwTH9zubpjyrT326HqHfK8ZBqqKJpEI0yURuymw5KLgwAUu/Q 2A0bFwbsVjhDmErXHf/cXffylEdx7hnM6Iv0nFbD2cmHYDNzGzcC52logs2FNk4o uE/3uBtSyCz6v0nZ =iZAt -----END PGP SIGNATURE----- --=-=-=-- From unknown Wed Sep 24 05:11:10 2025 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration). Resent-From: Attila Lendvai Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Thu, 23 Dec 2021 15:22:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Xinglu Chen Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , 52600@debbugs.gnu.org, Maxim Cournoyer , Andrew Tropin Reply-To: Attila Lendvai Received: via spool by 52600-submit@debbugs.gnu.org id=B52600.164027288416278 (code B ref 52600); Thu, 23 Dec 2021 15:22:01 +0000 Received: (at 52600) by debbugs.gnu.org; 23 Dec 2021 15:21:24 +0000 Received: from localhost ([127.0.0.1]:34631 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n0PuF-0004ET-K0 for submit@debbugs.gnu.org; Thu, 23 Dec 2021 10:21:24 -0500 Received: from mail-4317.proton.ch ([185.70.43.17]:45594) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n0PuD-0004EG-Th for 52600@debbugs.gnu.org; Thu, 23 Dec 2021 10:21:22 -0500 Date: Thu, 23 Dec 2021 15:21:10 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lendvai.name; s=protonmail3; t=1640272874; bh=noMfY8Q3U7bw2EVNDN2QuvcpD/nlKbGIa+bQhhQZfC8=; h=Date:To:From:Cc:Reply-To:Subject:Message-ID:In-Reply-To: References:From:To:Cc; b=sre+Q4FoGcKn78i+/8fl70iq/fKcA4pdVp4n6Kux5ADpf0kSALrHykxm+/VcmkjfC TGL2pyRys0gsE64S15fAKrMKICkag7sdLlyiIM27N3pO5JXJVeeMUpeN0sNK0XaVJ7 OahhXWYGCC8uBnOgzH5OwUWorS4nPPVduKp2aEenXq4R7vwDlUC8AjA0qKAEGyWcuM Rbs8Sh+vK1F+AITY2kzasCXxceSUn8hAo+edeqfckWDMlhpHNLrirbTlOlmhHVttEc /xunaHhMTZqTxS9CNYbm6KiSvMt/9H90HGksfTR4217TmH/1f8gwQlGAf0WYFclOBr N5sVBhZL4TzUw== From: Attila Lendvai Message-ID: In-Reply-To: <87a6grcwh7.fsf@yoctocell.xyz> References: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> <877dbwz3r7.fsf@gnu.org> <87ilvfd2lx.fsf@yoctocell.xyz> <87a6grcwh7.fsf@yoctocell.xyz> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-1.2 required=10.0 tests=ALL_TRUSTED,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF shortcircuit=no autolearn=disabled version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on mailout.protonmail.ch X-Spam-Score: -0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) > > i was expecting it to be possible to have a field like: > > > > (foo > > (maybe-integer?)) > > A =E2=80=98maybe-=E2=80=99 type doesn=E2=80=99t necessarily have to have = a default value set to > =E2=80=98disabled=E2=80=99. The default value of the =E2=80=98foo= =E2=80=99 field could just as well be > =E2=80=983=E2=80=99 or something. i know. but what i want is a field that is not initialized to any value, and a way to identify that fact in the service code (e.g. to derive a default value from another field). example: my service has a swarm-name field, and the service's unix user name is derived from it as "swarm-${swarm-name}" -- unless it is set by the user and overrides it, that is. in this case i can't set the field using the default value mechanism of define-configuration (i.e. at construction-time), because the default value is not a constant. the derivation of the default value must be done by the service's code, and it must be able to detect fields that were not set (i'm deliberately staying away from the word 'undefined' here, because the current codebase uses it, together with "disabled", in a strange way). > > and its behavior would be to hold an undocumented value by default, > > that the service implementations need to check for using a public > > predicate function. > > What do you mean by =E2=80=9Cundocumented value=E2=80=9D? a value that is opaque to the user, and can only be detected by a predicate (and possibly constructed by another function or through an exported global variable). > > some of the config values in my service can conditionally derive its > > default value based on the value of other fields. > > I don=E2=80=99t think this is possible with =E2=80=98define-configuration= =E2=80=99 yet. But it > would be a nice feature to have. i don't think it belongs to the define-configuration macro, because it would greatly increase the complexity of its DSL/implementation for little in return; one can always cover the few complex cases from the scheme code of the service. > > i need to be able to differentiate between undefined or user provided > > field values (i.e. completely independent of anything related to > > serialization). > > Maybe we could change =E2=80=98undefined=E2=80=99 to instead be an except= ion, which will > raised when the user doesn=E2=80=99t provide anything. that would make the above example/scenario impossible. although... you're probably using 'undefined' in the strange way that it is currently used in the code. i think the nomenclature should be clarified (regardless of what's in the current codebase). here's my proposal: 1) undefined: no value was provided, neither at construction time, nor as a default value in define-configuration. 2) missing: a value must be provided at construction time, but it wasn't. signalling an error at construction time in case of 'missing' is probably a good idea. but then 2) is mostly covered by the type predicates already, no? if i define the type as INTEGER? (i.e. not MAYBE-INTEGER?), then it'll already signal an error in that case. > > maybe we should use guile's undefined, and undefined? predicate > > (which is sadly a macro). or reexport an undefined? function, and > > shadow guile's macro? it's messy, and guile specific. > > I am not familiar with Guile internals, but I think that > =E2=80=98#=E2=80=99 is just a thing that the pretty-printer = prints. Maybe it's also a special type/value (to the point that it has its own heap object tag in Guile for which Guile's UNDEFINED? macro checks for; see https://www.gnu.org/software/guile/manual/guile.html#index-undefined_003f). > we could use =E2=80=9Cproper=E2=80=9D Maybe types, like in SRFI-189[1]? > [1]: Using https://srfi.schemers.org/srfi-189/srfi-189.html i don't immediately see its benefits here, but i'll need to get more familiar with this srfi. thanks for the pointer! > > or maybe we could use a heap object of an unusual/private type in a > > global private variable to represent undefined field values, and add a > > public predicate to test for it. using a cons cell for this is > > tempting, but it would leak implementation details for fields of type > > cons?. i'm new to scheme, but the best candidate is maybe a private > > dummy record instance? > > But what if a user wants to set a field to =E2=80=98disabled=E2=80=99 (be= cause they > don=E2=80=99t want anything to get serialized), then that record would ha= ve to > be public. yes, but preferably through a global variable or a function. my point is that the object's type/content should be opaque for the users. > > i'd add a configuration-undefined-value? predicate, and also add a > > configuration-defined-value? whose semantics is to return the value > > itself, or #false when undefined. it comes handy in (or > > (defined-value? foo) 42) patterns for non-boolean fields. > > But what if the value itself is #f? You wouldn=E2=80=99t be able to disti= nguish > between the cases where the value is undefined and when the value is #f. it's a user error when it is used on fields that may legitimately hold the #false value. > I don=E2=80=99t really see a use of having that functionality; do you hav= e any > examples when this would be useful to have? an example: the unix-user field of a service. 1) not specified by the admin =3D> generate a default user name 2) admin sets it to a string =3D> use that as user name 3) admin sets it to undefined (whichever value/API we use to mark the undefined value) =3D> don't create a unix user for the service, run it as root instead. but again, i'm not advocating for define-configuration to support this use-case. this example can easily modelled by e.g. using 'run-as-root as the default value in define-configuration, and the service code checking for it. > The second paragraph explains this, no? Or do you think it can be > improved? true, that should be enough. i'm also realizing that i'm talking about 1) how to change the code in (guix service configuration) under a ticket that discusses 2) the documentation of the current codebase. i'll cook up a patch that implements what i'm trying to describe above, and which is flexible enough to cover my use-cases. and then 1) can be continued under that ticket. - attila From unknown Wed Sep 24 05:11:10 2025 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration). Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Thu, 06 Jan 2022 14:21:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Xinglu Chen Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , Attila Lendvai , 52600@debbugs.gnu.org, Andrew Tropin Received: via spool by 52600-submit@debbugs.gnu.org id=B52600.16414788498756 (code B ref 52600); Thu, 06 Jan 2022 14:21:01 +0000 Received: (at 52600) by debbugs.gnu.org; 6 Jan 2022 14:20:49 +0000 Received: from localhost ([127.0.0.1]:39958 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n5TdI-0002HA-UO for submit@debbugs.gnu.org; Thu, 06 Jan 2022 09:20:49 -0500 Received: from mail-qt1-f178.google.com ([209.85.160.178]:43588) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n5TdF-0002Gw-M7 for 52600@debbugs.gnu.org; Thu, 06 Jan 2022 09:20:48 -0500 Received: by mail-qt1-f178.google.com with SMTP id q14so2360337qtx.10 for <52600@debbugs.gnu.org>; Thu, 06 Jan 2022 06:20:45 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=D/pQakQMS89KS09gBz9L9dUIgxdQALIPitaOn5ZgA/4=; b=SFbJzyS7sZbgYsmmQLB5xt8MK0rBBiYPNlosNWzBI99Fj5NVOXFs35IcesU8d6Iv8o RevtkImnKIjPFkH1ZrLZ3OM8i7kiesT980BtW+gJ1oMBR8BPpiNUfsDVPzImG1L5krtK SDkDVp6GLhI2i4sf6cLz2XNRCatdFG7JlSt0lSTlvuw5z6CPm/WLOD08YEX/unYl4eSU hL27W25MdvE8spYI1MPbDutVZokbuo9AZb6o0gWvzXrxMaooSyKd6/JWt0lt6bn9qUQI +Im/+pfFeUG+++cSH0nlD5p6t/Mej9sv4ZEkQ9bWTS5v6EQYyhdBHd3YQiyhz71W0uKi ppAw== 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:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=D/pQakQMS89KS09gBz9L9dUIgxdQALIPitaOn5ZgA/4=; b=dPslNfXUMkRNiyHvqBdd493C3p3tleXbusnbnyeepGDqEpGbf38pmB3S9v7gxtgp70 RHrfPLatPiPPGxU0VM8xiA9wNEndWfOuUZvgZLfJxNIlPxIsUE3L9dr+SPWXOk+2BLHZ UsS+2cO98ApPLovQ7yM6LVs/qyJVBqP6ymxfjg+bmuoHL2I01hH3CEtLE9tmYMlmVAi+ gzaDOAdHJ4cBcgnIrTK8qxfaEQJwDUgpssZO0xnYFLyyYvkr7YxXA56ttIlpI+UbxhBT SQc4G565zGGLLohpZX6XJ6VevCcaJ6MdklzQN1Q5/yUJVmTeT8tnxm7gd5+T71+8/NPv y9Dg== X-Gm-Message-State: AOAM5301CjieTg8kTjTlCZ7A544nMGdYGns/1na3L9riGO/pKhGcTQvH KDzdmRM/cidTQn1uJehxOz4= X-Google-Smtp-Source: ABdhPJyr7q4m5jG+WqksfC0e3soBODpYI+z87+Ei4UoV8yszebBFfSQXLxJiBegUhT1g+GZ4+mcbeg== X-Received: by 2002:ac8:7fcc:: with SMTP id b12mr52809492qtk.164.1641478840198; Thu, 06 Jan 2022 06:20:40 -0800 (PST) Received: from hurd (dsl-10-146-199.b2b2c.ca. [72.10.146.199]) by smtp.gmail.com with ESMTPSA id r16sm1747811qta.46.2022.01.06.06.20.39 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Jan 2022 06:20:39 -0800 (PST) From: Maxim Cournoyer References: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> <877dbwz3r7.fsf@gnu.org> <87ilvfd2lx.fsf@yoctocell.xyz> Date: Thu, 06 Jan 2022 09:20:38 -0500 In-Reply-To: <87ilvfd2lx.fsf@yoctocell.xyz> (Xinglu Chen's message of "Thu, 23 Dec 2021 11:42:18 +0100") Message-ID: <87y23tq72h.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Score: 2.0 (++) 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: Hi Xinglu, Sorry for jumping in late. Xinglu Chen writes: Content analysis details: (2.0 points, 10.0 required) pts rule name description ---- ---------------------- -------------------------------------------------- 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record 2.0 PDS_OTHER_BAD_TLD Untrustworthy TLDs [URI: yoctocell.xyz (xyz)] -0.0 SPF_PASS SPF: sender matches SPF record 0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail provider (maxim.cournoyer[at]gmail.com) 0.0 RCVD_IN_MSPIKE_H3 RBL: Good reputation (+3) [209.85.160.178 listed in wl.mailspike.net] -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at https://www.dnswl.org/, no trust [209.85.160.178 listed in list.dnswl.org] 0.0 RCVD_IN_MSPIKE_WL Mailspike good senders X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 1.0 (+) Hi Xinglu, Sorry for jumping in late. Xinglu Chen writes: >> As for =E2=80=98define-configuration=E2=80=99 vs. (guix records) vs. SRF= I-9=E2=80=A6 I don=E2=80=99t >> think we really discussed the issue or agreed on something. [...] > Agreed, since =E2=80=98define-configuration=E2=80=99 & friends are now do= cumented, it > makes even more sense to use them. > >> Thanks for substantially improving the manual! I haven't reviewed the feasibility yet, but since Guix records now have "sanitizers" that can be used to validate the field values, I have been wondering if these could be used in define-configuration. Anyway, thanks a lot for improving and documenting 'define-configuration' :-). Maxim From unknown Wed Sep 24 05:11:10 2025 X-Loop: help-debbugs@gnu.org Subject: [bug#52600] [PATCH] doc: Document (gnu services configuration). Resent-From: Attila Lendvai Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Tue, 18 Jan 2022 09:25:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 52600 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Xinglu Chen Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= , 52600@debbugs.gnu.org, Maxim Cournoyer , Andrew Tropin Reply-To: Attila Lendvai Received: via spool by 52600-submit@debbugs.gnu.org id=B52600.164249786426289 (code B ref 52600); Tue, 18 Jan 2022 09:25:02 +0000 Received: (at 52600) by debbugs.gnu.org; 18 Jan 2022 09:24:24 +0000 Received: from localhost ([127.0.0.1]:48981 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n9kj1-0006pu-Ki for submit@debbugs.gnu.org; Tue, 18 Jan 2022 04:24:23 -0500 Received: from mail-4317.proton.ch ([185.70.43.17]:18430) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1n9kiz-0006pg-3H for 52600@debbugs.gnu.org; Tue, 18 Jan 2022 04:24:21 -0500 Date: Tue, 18 Jan 2022 09:24:13 +0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lendvai.name; s=protonmail3; t=1642497854; bh=7f42WbWDO/ctmYep9j47kdb/IUnVMc8vMjiQC1sWm4E=; h=Date:To:From:Cc:Reply-To:Subject:Message-ID:In-Reply-To: References:From:To:Cc; b=pdKPrCMj+MkfcFZm2GXJc1FM8CTwSW/ip+/ExIrSAABR2vp46uLu7rkMoAPv7xGO5 J5sHfY/Dg4Tlmg4tnaZMB9EEAxa+QdtEK2n9QCZ5NjtuqRyBBkZEWykn56ws2veLaZ ZR/EoIrHVawIT6jM89L6Cn1RE7Y4ow5GnfqhErlWNvnhwZykEfUwUjduO0P3Q3e+FQ Zix3GH0XRsgVu///idrzUjFy/jbcMar4wOlj8Tui4VaSrPeGfATHsoYaanqGY7Dnfp XWdtbrUgbSZqs30O3g0IwGH0LFU+qTmjZROm+s0OfIkUUmefbAAEUmmYlg1dxpswSn PYnlNEtjD8Ykg== From: Attila Lendvai Message-ID: In-Reply-To: <87a6grcwh7.fsf@yoctocell.xyz> References: <665c4d2070de80af1d3594a268f0f6d3fb596d15.1639839498.git.public@yoctocell.xyz> <877dbwz3r7.fsf@gnu.org> <87ilvfd2lx.fsf@yoctocell.xyz> <87a6grcwh7.fsf@yoctocell.xyz> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Spam-Status: No, score=-1.2 required=10.0 tests=ALL_TRUSTED,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF shortcircuit=no autolearn=disabled version=3.4.4 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on mailout.protonmail.ch X-Spam-Score: 0.0 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -1.0 (-) > I am not familiar with Guile internals, but I think that > =E2=80=98#=E2=80=99 is just a thing that the pretty-printer = prints. Maybe > we could use =E2=80=9Cproper=E2=80=9D Maybe types, like in SRFI-189[1]? > > [1]: Using https://srfi.schemers.org/srfi-189/srfi-189.html this is indeed a good idea here, thanks for drawing my attention to it! FTR, i have added guile-srfi-189 in this (not yet applied) patch: https://issues.guix.gnu.org/53317 i think Maybe and Nothing covers exactly what i need here. my plan is to get guile-srfi-189 into master, then make sure it can be used in the Guix codebase, and then prepare a patch for the configuration code that uses Nothing to represent unspecified values. -- =E2=80=A2 attila lendvai =E2=80=A2 PGP: 963F 5D5F 45C7 DFCD 0A39 -- Government means never having to say you're sorry=E2=80=A6