From patchwork Mon Sep 11 04:26:00 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxim Cournoyer X-Patchwork-Id: 53717 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 A373627BBE9; Mon, 11 Sep 2023 05:27:44 +0100 (BST) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-2.7 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FROM,MAILING_LIST_MULTI, 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 6028E27BBE2 for ; Mon, 11 Sep 2023 05:27:42 +0100 (BST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qfYVr-0001DO-Ng; Mon, 11 Sep 2023 00:27:03 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qfYVn-0001Cz-L9 for guix-patches@gnu.org; Mon, 11 Sep 2023 00:26:59 -0400 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qfYVn-0005sw-Dm for guix-patches@gnu.org; Mon, 11 Sep 2023 00:26:59 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qfYVr-0005ag-7k for guix-patches@gnu.org; Mon, 11 Sep 2023 00:27:03 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#65860] [PATCH 4/4] doc: Add new 'Circular Module Dependencies' section. Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Mon, 11 Sep 2023 04:27:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 65860 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 65860@debbugs.gnu.org Cc: mhw@netris.org, Maxim Cournoyer Received: via spool by 65860-submit@debbugs.gnu.org id=B65860.169440642121467 (code B ref 65860); Mon, 11 Sep 2023 04:27:03 +0000 Received: (at 65860) by debbugs.gnu.org; 11 Sep 2023 04:27:01 +0000 Received: from localhost ([127.0.0.1]:51796 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qfYVp-0005a8-3q for submit@debbugs.gnu.org; Mon, 11 Sep 2023 00:27:01 -0400 Received: from mail-qv1-xf31.google.com ([2607:f8b0:4864:20::f31]:58718) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qfYVn-0005Za-6l for 65860@debbugs.gnu.org; Mon, 11 Sep 2023 00:27:00 -0400 Received: by mail-qv1-xf31.google.com with SMTP id 6a1803df08f44-64a5f9a165eso22684446d6.1 for <65860@debbugs.gnu.org>; Sun, 10 Sep 2023 21:26:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1694406409; x=1695011209; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=qZypnKqMIWx8K8eRkflYklhJ9uH6uJBtpu43mfr+Z08=; b=n36VRssqRGfEk4WTLhCmd/RGc2Z/0v2GLp7XHGiVbZlLkwQm1VHgWPM0sALmo4A72A 4cEXy/wdPVcQPGTz0ozOAMpzI6gy0Z6xfaxDGKajE4yZqhUnAT+Ts/z6Ng49l5gW5rr9 voyC4hFrNynM33PpcG1h0Bs8pDKqLbB6Q28ojt1pC2mB1xBQL/q4ZFmEjl8WuKmAlsGy U0zpFdEhRHhG2WwlGKIqTeVqsuZAxtKjWO2c+JV8BcdMjywQOVXSvX/QwgAlXPsfi+qu ropCQUf78C5pCOcUnjeZ9hM939ZlHoWmDgAdy/csINoApzjoTJlnmmXuT1PIfWuMZ26D gCcQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1694406409; x=1695011209; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=qZypnKqMIWx8K8eRkflYklhJ9uH6uJBtpu43mfr+Z08=; b=YTPecb1tWKGy5L7+nM7yUu17xFWaxB9ZKdD6lEiNRqI73XcmH53O/GhPm8ccCKcmhU JrezGSxTrwws+R8Vv4vxmrs7NEI5ILy4iwu2N6pxuWcJAxNvovRmOx91d458DBMSUYQw mRf1Sqcxi7f08LzbqNU+zwekEzMeOfb1qNeMg2VRcv5s/rTK8rC1NV9vox0fHeBC9D3+ +SnybnKe3F/Umwc5jyjXvQyfocBgPlk0tPgmhyNbrGcNxA0O5csrMYHg02Wu98+oq8L4 TiSAAPmzZ+xXReH+99p/OUTuCp92E3gSwkJKrmvJfRFnW3sfYB0Nz8arSuHFgcprh+tV 87cA== X-Gm-Message-State: AOJu0YxRT7uUUNDUmzEW3hhE6dGYe8qMo8otM1SQ8UbpicealoGSrUwA OjKbeDmWI5gx9KZCBWWJgTBpfbu/2Vo= X-Google-Smtp-Source: AGHT+IFpwgVmSPMONm7SPS0ay6UfU5vTD0t8IwBtDX2x8r0/oY0S/3dywa7oAub8IP369DR75TAHpQ== X-Received: by 2002:a0c:9e89:0:b0:64f:50e2:c559 with SMTP id r9-20020a0c9e89000000b0064f50e2c559mr7762123qvd.2.1694406409460; Sun, 10 Sep 2023 21:26:49 -0700 (PDT) Received: from localhost.localdomain (dsl-155-89.b2b2c.ca. [66.158.155.89]) by smtp.gmail.com with ESMTPSA id c8-20020a0cf2c8000000b0064f778c8165sm2608923qvm.64.2023.09.10.21.26.48 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 10 Sep 2023 21:26:49 -0700 (PDT) From: Maxim Cournoyer Date: Mon, 11 Sep 2023 00:26:00 -0400 Message-ID: X-Mailer: git-send-email 2.41.0 In-Reply-To: References: MIME-Version: 1.0 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-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * doc/contributing.texi (Circular Module Dependencies): New subsection. --- doc/contributing.texi | 56 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/doc/contributing.texi b/doc/contributing.texi index a0da871f1a..67ceff4fdb 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -449,6 +449,7 @@ Packaging Guidelines * Version Numbers:: When the name is not enough. * Synopses and Descriptions:: Helping users find the right package. * Snippets versus Phases:: Whether to use a snippet, or a build phase. +* Cyclic Module Dependencies:: Going full circle. * Emacs Packages:: Your Elisp fix. * Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. @@ -720,6 +721,61 @@ Snippets versus Phases using build phases. Refer to the @code{origin} record documentation for more information (@pxref{origin Reference}). +@node Cyclic Module Dependencies +@subsection Cyclic Module Dependencies + +While there cannot be circular dependencies between packages, Guile's +lax module loading mechanism allows circular dependencies between Guile +modules, which doesn't cause problems as long as the following +conditions are followed for two modules part of a dependency cycle: + +@cindex rules to cope with circular module dependencies +@enumerate +@item +Macros are not shared between the co-dependent modules +@item +Top-level variables are only referenced in delayed (@i{thunked}) package +fields: @code{arguments}, @code{native-inputs}, @code{inputs}, +@code{propagated-inputs} or @code{replacement} +@item +Procedures referencing top-level variables from another module are not +called at the top level of a module themselves. +@end enumerate + +Straying away from the above rules may work while there are no +dependency cycles between modules, but given such cycles are confusing +and difficult to troubleshoot, it is best to follow the rules to avoid +introducing problems down the line. + +@noindent +Here is a common trap to avoid: + +@lisp +(define-public avr-binutils + (package + (inherit (cross-binutils "avr")) + (name "avr-binutils"))) +@end lisp + +In the above example, the @code{avr-binutils} package was defined in the +module @code{(gnu packages avr)}, and the @code{cross-binutils} +procedure in @code{(gnu packages cross-base)}. Because the +@code{inherit} field is not delayed (thunked), it is evaluated at the +top level at load time, which is problematic in the presence of module +dependency cycles. This could be resolved by turning the package into a +procedure instead, like: + +@lisp +(define (make-avr-binutils) + (package + (inherit (cross-binutils "avr")) + (name "avr-binutils"))) +@end lisp + +Care would need to be taken to ensure the above procedure is only ever +used in a package delayed fields or within another procedure also not +called at the top level. + @node Emacs Packages @subsection Emacs Packages