From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id 9nZ2AQCif2BTGwAAgWs5BA (envelope-from ) for ; Wed, 21 Apr 2021 05:54:40 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id qFWsN/+hf2C4YgAAB5/wlQ (envelope-from ) for ; Wed, 21 Apr 2021 03:54:39 +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 75D29BB43 for ; Wed, 21 Apr 2021 05:54:39 +0200 (CEST) Received: from localhost ([::1]:60748 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lZ3wk-0003At-9A for larch@yhetil.org; Tue, 20 Apr 2021 23:54:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:60426) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lZ3wW-0003AZ-S2 for guix-devel@gnu.org; Tue, 20 Apr 2021 23:54:24 -0400 Received: from mail-qk1-x736.google.com ([2607:f8b0:4864:20::736]:45042) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lZ3wR-0007Zh-SI for guix-devel@gnu.org; Tue, 20 Apr 2021 23:54:23 -0400 Received: by mail-qk1-x736.google.com with SMTP id x11so41626597qkp.11 for ; Tue, 20 Apr 2021 20:54:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version; bh=zLFOPPfDbYjCB1xqoT1uzvvctnhq4pHsr5AN3IsoR10=; b=KdEI9OEMwCEAYKV2bDC4GBMFlLlVeMAg+DOBky47UTO5OUPrudaYqFmfYgS5h8P9DJ /JdUJQx46OEzZOZBIBEhd1Muhu7E9KanBp1Tbhs58SB6BtpQMG8+ggEospDjuR9nuQaf zNFknsSqCMVqsIMgs2WPgbAXGh0X4X2Pcur8OiA1DQ1yd6v68gJZawNUtYkgd1yGAQpE VyQrGlTLJtazmuaNCZ+oJ4vHs3DfhFlb2Gu7jDwvOZZxpJz0l+JpAO2OzzvBz/G9Ha6O FsK4pvUg97Fz5cG792AKiyko/WeYCnazb7BRmSioUoxmecvwys2nHZvFCZq/9Vwtu82s nimQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version; bh=zLFOPPfDbYjCB1xqoT1uzvvctnhq4pHsr5AN3IsoR10=; b=US80shcmMgLDvfWz+A+7pCaNnIhBBBvJfh0cENlKEYFhd/qd4T6ffgEsvjtjxUxiNG o0qG36zNgVjMIBPcHy/m09JFM2CWS4IXBLkxsWf1qg3dAIpCTSCl4NDayN7X1FDmb/Oo rZuhlPyc3P38/6wUWjHHBQTBwFA42cPha1GN2dwvxuROcarIpR8QSqdn/Box8XKagdKE L3ZmyrN8NGkWHv0fcjfNtb4P2O+tD5lJwL9Whr2xFrlhiEuHacDYdBme4+yuZD7Vlb11 1NRRgYi7Q9iunPKwQuiwmKgZBZqCXb5lJ3NRqtlMsyT/JMRNAKtxxjSRScj2s2S7PCW9 mX9w== X-Gm-Message-State: AOAM532pEw28xANaborRoij6jFStK76dgcUknnXxRztU1Tmup+7H4iZ1 9UfWuNMPY5a1NPYpLWWgt603ZdBKXlvCaQ== X-Google-Smtp-Source: ABdhPJzh3WlzbrkjhHmTKrnnFPy02nococyLd89M/1JyPuodcdRff+aajtf88aNJXRukXBIMEdxcNg== X-Received: by 2002:a37:b585:: with SMTP id e127mr16579636qkf.405.1618977258562; Tue, 20 Apr 2021 20:54:18 -0700 (PDT) Received: from hurd (dsl-205-151-56-5.b2b2c.ca. [205.151.56.5]) by smtp.gmail.com with ESMTPSA id z7sm1024718qkf.136.2021.04.20.20.54.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 20 Apr 2021 20:54:18 -0700 (PDT) From: Maxim Cournoyer To: Xinglu Chen Subject: Re: Best practices for writing services References: <878s6kqydj.fsf@yoctocell.xyz> Date: Tue, 20 Apr 2021 23:54:17 -0400 In-Reply-To: <878s6kqydj.fsf@yoctocell.xyz> (Xinglu Chen's message of "Thu, 18 Mar 2021 16:23:36 +0100") Message-ID: <87wnswcmxi.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2607:f8b0:4864:20::736; envelope-from=maxim.cournoyer@gmail.com; helo=mail-qk1-x736.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 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, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: guix-devel@gnu.org Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1618977279; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc: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=zLFOPPfDbYjCB1xqoT1uzvvctnhq4pHsr5AN3IsoR10=; b=kfxQbx0ho4d9pV+NRnL3W5aPYgXT12nl7kVHFGfS8I9FFaEejqgjphT6YgfvgGL5EDjzgj Bfz0x5fIRzGwxepPZXisjoQk8UrAUW73bY9mPbbaYMRIDq0wHlpZx2RWJ8XA4QgL2WZIKg 4Xs7uCDsHw7Nd8E53NjBHECvVJY5TM2C5ICbKzEIQ8pDHIL3T6oatnFGEIBsrNCZ0DySL0 wOuzPa3vpM3iUdvqwL6asbQthdKDJsdFjU08/SjPqMrbqEZDJz5BxZ60eFm5AfOuHKMqm1 i0CQ7hf0QmXTFpWCClwfL7cmcLdgkcCUB3QpOT8BtzA22XqsD4rf2JwpaoP2yw== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1618977279; a=rsa-sha256; cv=none; b=P5b7ahuxBiUqFXpma5W1fVLWxJNb18UrIgFZXnQ4SAzl11As3EL1z7aNHxzfXBoVoYQv+e wLWbvAKLQIaWzv+AEeDQePsyEDH1JuGXWIX000EuJ8wDJv8yfncs5jWsP0lWy6dlkYHv9Z 5uDiO1ed6606gQ8C8o/AgCd7c36xqsOViJcGLkg8gIcSFMlmlNE9YvFvr7RbUzCBKNGvhh dGue3e+x9G+zYFFW5wNhLMh38BHdz62NHcxxaH6jbSpIp7W5Rh4vmbXnEVnf+J8T06Y1Gp 187sG269kGGvIj96b4WojNf2SIyRFdvxNO+u6ctKXbzsLWNk8ZD1+U8/PDkANQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20161025 header.b=KdEI9OEM; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of guix-devel-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-devel-bounces@gnu.org X-Migadu-Spam-Score: -3.14 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20161025 header.b=KdEI9OEM; dmarc=pass (policy=none) header.from=gmail.com; spf=pass (aspmx1.migadu.com: domain of guix-devel-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-devel-bounces@gnu.org X-Migadu-Queue-Id: 75D29BB43 X-Spam-Score: -3.14 X-Migadu-Scanner: scn0.migadu.com X-TUID: hgJL9GKBU2nE Hi Xinglu, Xinglu Chen writes: > Hi Guix, > > I am going to write an mcron service for `guix home`[1][2] and before > proceding, I would like to get some suggestions on what the best > practices are for writing services in Guix. > > Currently there seems to be two main ways to do this, the first one > is the define one or more records for the configuration field of a > service using `define-record-type*`, see the tor service in (gnu > services networking) for example. The other method is to use > `define-configuration` to declare the configuration fields of a service, > see the transmission service in (gnu services file-sharing) for example. > > The first method seems to be the more common one but the developer > usually has to write a lot of things manually. The "real" configuration > file for the program or is usually created by concatenating a bunch of > strings and the developer has to write documentation for all the > configuration fields manually. > > The second method removes quite a lot of boilerplate and the developer > will define different serializers that convert scheme syntax like lists, > alist, boolean... to the "real" configuration syntax of the program. It > also does some automatic typechecking to some degree and allows the > developer to write docstrings for each configuration field. There is > then a procedure called `generate-documentation` which can automatically > generate texinfo documenation from the docstrings. > > I couldn't find any information in the manual regarding what conventions > should be used when writing services for Guix and would like to hear > from more experienced Guix hackers what the best practices are. That's a very good question, which I asked myself recently when attempting to write my first non-trivial service for Guix (jami-daemon-service-type). I'd say 'define-configuration' is technically superior because of the automatic type checking it provides. It's also neat to be able to define the doc at one place and auto-generate it (although that's still manual for now). It has definitely been collecting some dust compared to the simpler approach using 'define-record-type*' directly, and the doc output it can generate doesn't match what is currently the norm in the manual, so it'd need a bit of a refresh. Still, I see great potential for define-configuration. Maxim