From patchwork Mon Feb 28 18:51:16 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Attila Lendvai X-Patchwork-Id: 37556 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 1586F27BBE9; Mon, 28 Feb 2022 18:52:15 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-3.7 required=5.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,MAILING_LIST_MULTI,RCVD_IN_MSPIKE_H5,RCVD_IN_MSPIKE_WL, SPF_HELO_PASS autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 8577227BBE9 for ; Mon, 28 Feb 2022 18:52:14 +0000 (GMT) Received: from localhost ([::1]:55144 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nOl81-0002HZ-Mo for patchwork@mira.cbaines.net; Mon, 28 Feb 2022 13:52:13 -0500 Received: from eggs.gnu.org ([209.51.188.92]:57238) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nOl7q-0002HC-3s for guix-patches@gnu.org; Mon, 28 Feb 2022 13:52:02 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:40879) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nOl7p-0003OV-Rl for guix-patches@gnu.org; Mon, 28 Feb 2022 13:52:01 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nOl7p-0002Fl-Pq for guix-patches@gnu.org; Mon, 28 Feb 2022 13:52:01 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#54199] [PATCH] doc: Add 'Working on Shepherd' section. Resent-From: Attila Lendvai Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Mon, 28 Feb 2022 18:52:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 54199 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 54199@debbugs.gnu.org Cc: Attila Lendvai X-Debbugs-Original-To: guix-patches@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.16460743138645 (code B ref -1); Mon, 28 Feb 2022 18:52:01 +0000 Received: (at submit) by debbugs.gnu.org; 28 Feb 2022 18:51:53 +0000 Received: from localhost ([127.0.0.1]:34776 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nOl7h-0002FN-3d for submit@debbugs.gnu.org; Mon, 28 Feb 2022 13:51:53 -0500 Received: from lists.gnu.org ([209.51.188.17]:45610) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nOl7f-0002FG-Sj for submit@debbugs.gnu.org; Mon, 28 Feb 2022 13:51:52 -0500 Received: from eggs.gnu.org ([209.51.188.92]:57200) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nOl7f-0002Gx-LF for guix-patches@gnu.org; Mon, 28 Feb 2022 13:51:51 -0500 Received: from [2a00:1450:4864:20::52d] (port=38488 helo=mail-ed1-x52d.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nOl7d-0002yV-FV for guix-patches@gnu.org; Mon, 28 Feb 2022 13:51:51 -0500 Received: by mail-ed1-x52d.google.com with SMTP id s24so18941305edr.5 for ; Mon, 28 Feb 2022 10:51:48 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=sender:from:to:cc:subject:date:message-id:mime-version :content-transfer-encoding; bh=Z4BoOD9lLPDpuk3lB9HLFRG0sdx1TbzYCh+yrzoGLWY=; b=cFSDi+kkwnl5N629OjiA/F5GYYrj+2+VJFC6hGMO+RJj8fuM8Fo5kJrFfAwho3+QTw 1x0gpIzt/HMd2/KLqNS/KkFiX1wOj8HEXzabHswO48DU+I2zm/U5jgGfDVKqLAbWPHyY qFAspBWkCMxIiU2XJsN8dsbuKPmVQ89FEGTJb567IK/JIn+UtimiJ8s2CTtFVPyxT5iI Y9PHWkbnXscNEEEy+y/LkPcjkhyeBMyDC6xTWxLbRyPsU+xPLN4fc0KKLHNjy5bOj+dH amgql2NUt5JunwRw9BYzGxyQ2eQAVRXMwc8ipiZYfwz1v9CWLHeAyWog5yrPb85qw5hE BoQg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :mime-version:content-transfer-encoding; bh=Z4BoOD9lLPDpuk3lB9HLFRG0sdx1TbzYCh+yrzoGLWY=; b=bUubqudWwX/crdssWySohlokRnKBLpuVmKT3vCUfgOqR3BEyZsrBrW1QIr9iqw0Xpo Q2XaaqkcQJVg79XlJGBpwtnKQjYtw1Lo0EieYNgR/TXMCP7LSn7mgeOU8sAcvILPUuvD pUQoosQPoj7ubOg1sxDl4nlWP+vQxIUdXVSh2qf8kNjWRFzEM80isgjOs+UyPcZW2I9f cG9GGwfrbPLeorf9xncEaMR5S+vP2IORoi3F17UTx1ZRuzzUoM66AToKWaZwfXB9x0VS gzeZLW14Wzswim9VLBsP0nORU1UGXraMwZKsUpxdsAz7vNeEWmnUWwfao2P5urlvBZi9 53xA== X-Gm-Message-State: AOAM5318TTiTojN8Nty5hF32+egP27wEkEYKlyehH9v0LDpHf4yjLAJR kIIz9AOen0AGf4YVPrWsSVZfBxCOXu8= X-Google-Smtp-Source: ABdhPJz3p/J43mkaBqKZZYGDlxQmRUXxN3P+X+P1hhcmrEfuxFv4DOJBFh82u2JTVArhrfu6O0liTQ== X-Received: by 2002:a50:9d47:0:b0:40f:9d3d:97b6 with SMTP id j7-20020a509d47000000b0040f9d3d97b6mr21547150edk.392.1646074307606; Mon, 28 Feb 2022 10:51:47 -0800 (PST) Received: from lelap.local (catv-89-132-245-188.catv.fixed.vodafone.hu. [89.132.245.188]) by smtp.gmail.com with ESMTPSA id ee21-20020a056402291500b00410d4261313sm6256428edb.24.2022.02.28.10.51.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 28 Feb 2022 10:51:47 -0800 (PST) From: Attila Lendvai Date: Mon, 28 Feb 2022 19:51:16 +0100 Message-Id: <20220228185115.28042-1-attila@lendvai.name> X-Mailer: git-send-email 2.34.0 MIME-Version: 1.0 X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::52d (failed) Received-SPF: pass client-ip=2a00:1450:4864:20::52d; envelope-from=attila.lendvai@gmail.com; helo=mail-ed1-x52d.google.com X-Spam_score_int: 0 X-Spam_score: -0.1 X-Spam_bar: / X-Spam_report: (-0.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FORGED_FROMDOMAIN=0.249, FREEMAIL_FROM=0.001, HEADER_FROM_DIFFERENT_DOMAINS=0.249, PDS_HP_HELO_NORDNS=0.659, RCVD_IN_DNSWL_NONE=-0.0001, RDNS_NONE=0.793, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: "Guix-patches" X-getmail-retrieved-from-mailbox: Patches --- doc/contributing.texi | 91 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 91 insertions(+) diff --git a/doc/contributing.texi b/doc/contributing.texi index 207efc4ee6..d36b6e66e0 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -29,6 +29,7 @@ choice. * Tracking Bugs and Patches:: Keeping it all organized. * Commit Access:: Pushing to the official repository. * Updating the Guix Package:: Updating the Guix package definition. +* Working on Shepherd:: Modifying and testing Shepherd. * Translating Guix:: Make Guix speak your native language. @end menu @@ -1697,6 +1698,96 @@ This check can be disabled, @emph{at your own peril}, by setting the this variable is set, the updated package source is also added to the store. This is used as part of the release process of Guix. +@node Working on Shepherd +@section Working on Shepherd + +This chapter documents how to modify and test GNU@tie{}Shepherd +(@pxref{Shepherd Services}) in the Guix environment. + +There are two @emph{manifestations} of Shepherd in a Guix System: + +@table @code + +@item @emph{The Shepherd process} +The init process first started by the kernel (i.e. running as PID 1). +This is a Guile executable that is executing the @code{main} function of +the Shepherd codebase. Among other things, this is the process +responsible for starting and stopping Guix System services (i.e. daemon +processes). + +@item @emph{The Shepherd API} +The Scheme code of Shepherd, which is a dependency of certain packages +and the Guix codebase itself. A typical example of this is the Scheme +code implementing a Guix System service, e.g. the OpenSSH server service +(see @code{openssh-shepherd-service}). + +@end table + +Modifying the latter results in the recompilation of several dependant +packages, and it takes too long to be a reasonable edit-compile-test +cycle. But starting up a VM that merely uses a customized Shepherd init +process is a relatively quick operation. + +Luckily, not all changes to Shepherd require the recompilation of all +its dependencies. The rule of thumb here is that: + +@itemize + +@item +if you are making changes to the public API of Shepherd (i.e. anything +that may have compile-time effects on dependant packages, like adding or +removing public functions, or changing public macros, etc.), then you +will need to go through a full recompilation, so that the the Guix +codebase, and the dependant packages can observe the changes while they +are being compiled. + +@item +if you're only working on Shepherd's implementation (e.g. making +Shepherd's error handling more bullet proof), then it's enough to only +recompile Shepherd itself, and use the resulting package as the one that +gets started as the init process. + +@end itemize + +The @ref{Shepherd Services, @code{shepherd-configuration}} section +documents how you can replace the Shepherd process by specifying a +custom Shepherd package for an @code{operating-system} object. To get a +customized Shepherd package, you can simply make a copy of it in +@file{gnu/packages/admin.scm}, and change the @code{source} and +@code{version} field along these lines: + +@lisp +(define-public shepherd-dev-pid-1 + (package + (name "shepherd") + (version "dev-pid-1") + (source (git-checkout + (url "file:///my/path/shepherd/"))) + ... + )) +@end lisp + +To modify and use a new Shepherd API, you can change the @code{source} +and @code{version} field of the @code{shepherd} package in +@file{gnu/packages/admin.scm} along these lines: + +@lisp +(define-public shepherd ; do not change this + (package + (name "shepherd") + (version "dev") + (source (git-checkout + (url "file:///my/path/shepherd/") + (commit "[a commit hash]"))) + ... + )) +@end lisp + +To avoid excessive recompilation times, we pick a specific commit in the +latter, and only update it as needed. But the former will pick up any +newly recorded commit when we issue a @command{guix system vm +/path/to/my-test.scm}. + @cindex translation @cindex l10n @cindex i18n