From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id 8AHKNN8ZHWJYFgAAgWs5BA (envelope-from ) for ; Mon, 28 Feb 2022 19:52:15 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id iAX6Md8ZHWIJUwAA9RJhRA (envelope-from ) for ; Mon, 28 Feb 2022 19:52:15 +0100 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 771C91B933 for ; Mon, 28 Feb 2022 19:52:15 +0100 (CET) Received: from localhost ([::1]:55144 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nOl82-0002HZ-8M for larch@yhetil.org; Mon, 28 Feb 2022 13:52:14 -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 Content-Transfer-Encoding: 8bit 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+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1646074335; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=Z4BoOD9lLPDpuk3lB9HLFRG0sdx1TbzYCh+yrzoGLWY=; b=I6SBUWL0gfrc9/z7TBIZ4n1Xid0btvi47d+wNNHY6xQRGpl0GcDdRAN2lhDGfAAW1XyHrT 5oHyg53SW+FhRr1vEUqB3V62GTktVzqzLmsmg50sRJrh2IV4KXWwWNoB15X9W0CKhVReK6 ENJEmhusGPTb3Dld3DOj+afek1goaOWiWYwzC6DEO4QoNruUa0hJ2QqKp4jARKDLNwsHa+ 2dKdks9qMZ4pLU9syhz6lADumoiOvb1Wywt/G0srRfOumD4ZN4Fmzucwil4H3jiPhzTEX6 ovsPc05MR0ooex3vvMzdb4EdmMw+lfmaCHce83o5lFps+oRKAdAH0g4N3nB0NA== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1646074335; a=rsa-sha256; cv=none; b=pVbJ43u8iDtjamEP2JIbD2W2mH0XiajWQOFKkwUVrD3vMr/uhg5ITcP1SqDDJ+sel/5Nt8 NwLAuTcXatwIJfgWe607OtvXtKOP6P92BFMXBDB81midz8pDvglhItVW8Nbr6TI3gPezGl UyQDtfInl0TFz2eAnGm/al79HeK7okhoZAUdyTYrnC/N3wBW9XZqlswDijYUx8/H1AhNzi Lj2sXwE8nl74WkKW8YOof9sssGzQKvOAV/T7hFT0vxkBTw8BXG5Jr8nilR4cBiIVfAmTye du2jPzh9HC5nNtrYHHKFpILJ20HHwaRK0/dUIhm5OKKINu261NLCVVos7lSXMA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=cFSDi+kk; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: 0.81 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=cFSDi+kk; dmarc=none; spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 771C91B933 X-Spam-Score: 0.81 X-Migadu-Scanner: scn0.migadu.com X-TUID: +HRUZ9g9kiOv --- 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 -- 2.34.0