From patchwork Mon Sep 18 00:43:10 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Maxim Cournoyer X-Patchwork-Id: 54015 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 CFBA627BBEA; Mon, 18 Sep 2023 01:45:03 +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=ham 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 442D527BBE2 for ; Mon, 18 Sep 2023 01:45:00 +0100 (BST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qi2Nj-0003ym-Rg; Sun, 17 Sep 2023 20:44:55 -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 1qi2Ni-0003yW-9N for guix-patches@gnu.org; Sun, 17 Sep 2023 20:44:54 -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 1qi2Ni-0001Gc-0r; Sun, 17 Sep 2023 20:44:54 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1qi2Np-0001rc-ST; Sun, 17 Sep 2023 20:45:01 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#65860] [PATCH v2 3/3] doc: Add new 'Circular Module Dependencies' section. Resent-From: Maxim Cournoyer Original-Sender: "Debbugs-submit" Resent-CC: maxim.cournoyer@gmail.com, ludo@gnu.org, guix-patches@gnu.org Resent-Date: Mon, 18 Sep 2023 00:45:01 +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: Maxim Cournoyer , Maxim Cournoyer , Ludovic =?utf-8?q?Court=C3=A8s?= X-Debbugs-Original-Xcc: Maxim Cournoyer , Ludovic =?utf-8?q?Court=C3=A8s?= Received: via spool by 65860-submit@debbugs.gnu.org id=B65860.16949978457063 (code B ref 65860); Mon, 18 Sep 2023 00:45:01 +0000 Received: (at 65860) by debbugs.gnu.org; 18 Sep 2023 00:44:05 +0000 Received: from localhost ([127.0.0.1]:51678 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qi2Mu-0001pq-Tv for submit@debbugs.gnu.org; Sun, 17 Sep 2023 20:44:05 -0400 Received: from mail-qt1-x830.google.com ([2607:f8b0:4864:20::830]:52569) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1qi2Mp-0001oS-2S for 65860@debbugs.gnu.org; Sun, 17 Sep 2023 20:43:59 -0400 Received: by mail-qt1-x830.google.com with SMTP id d75a77b69052e-414b3b65e85so26094361cf.1 for <65860@debbugs.gnu.org>; Sun, 17 Sep 2023 17:43:51 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1694997825; x=1695602625; 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=CmoiUvwzRQcw75LFnEMihCQ967PVYN5TYCCEpNfllyQ=; b=MXwB1CyiNaRJS2I7jRbMRjubw5LtPECa4COl6CnMqRSKV/jWhkGjLoRnwI2AP8aP/2 yGDT5sMUjkWt+OowRx6hm2p/V3Whwd7Mr/0onn81mGJLBKx+h29LNcxxk0gujryPNrGO LGLcGtLzI95O3TKu0i3UJ3kJDrrEW8epaE2yzV6YqR7wX2Tn6TT6JQbjDnbN0oSnuzXJ jBgM6vPTZLHMF/9x2ItdhOi+yxPDTiClp+STq53z720Jg8GwtGNk/x44rQv7t4N7cmWv vAnS6Ft0QDHivDG2Jguh2S5vUTKf/L7JspjaWzq+wAN80xfUW5Gkc7Qjs12b4gPjaNrn YtXg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1694997825; x=1695602625; 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=CmoiUvwzRQcw75LFnEMihCQ967PVYN5TYCCEpNfllyQ=; b=PMePR/nRBG8uH2pSK58mLh65/RXlO8P5djDvT2qbLGjpsViRosnnPU4bnKBAMjityp hVl1040V13HhgNc5u0LPpBWqmkKsIrWQHQgN5I3T2FlcE7CBFrMd5Z+GNGI+38qMUwRj 250ACC9PQehY1wV6NF/p0ouagS/KP5OT468tgZSbkbvVSQau16HQB30ag1zOJvIhd0l5 762ZJj6/dpH6996C/ejYGXP8TXmEzOYFCtA3tBNoOFs10ZL8LPwlzVd5EamYWRG9+mm1 L0ZsxMWiZyuu7VR0L3VgS8U2JMjs+57CWF6KZm9z1NPVzxOlgIjOIlLNvTWWSaW/ZKW3 aglA== X-Gm-Message-State: AOJu0YyxP+LARLi73QJyhVVwqvLkc2UyGxfeZ9hL9DsfP+h/0d5CH3fF w5aCLa3X52PbzbJMLfmn9gwJpjl2IrQ= X-Google-Smtp-Source: AGHT+IEdp9W6knVZwnemWm9ChAwDia54Q9PJAZaKJVB6Lnd51FF3y9x9FgrIoxmWjy7Gi+2kfHr3HA== X-Received: by 2002:a05:622a:50f:b0:411:5528:64f6 with SMTP id l15-20020a05622a050f00b00411552864f6mr9060870qtx.27.1694997825336; Sun, 17 Sep 2023 17:43:45 -0700 (PDT) Received: from localhost.localdomain (dsl-10-149-131.b2b2c.ca. [72.10.149.131]) by smtp.gmail.com with ESMTPSA id cr8-20020a05622a428800b00403f1a7be90sm2662547qtb.88.2023.09.17.17.43.44 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 17 Sep 2023 17:43:44 -0700 (PDT) From: Maxim Cournoyer Date: Sun, 17 Sep 2023 20:43:10 -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. --- (no changes since v1) doc/contributing.texi | 56 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/doc/contributing.texi b/doc/contributing.texi index 156a6cb19e1..d99751f42cb 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -513,6 +513,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. @@ -784,6 +785,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