From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp1 ([2001:41d0:2:bcc0::]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id Ew2FFvkOc2BnggEAgWs5BA (envelope-from ) for ; Sun, 11 Apr 2021 17:00:09 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp1 with LMTPS id WPEpD/kOc2AOIwAAbx9fmQ (envelope-from ) for ; Sun, 11 Apr 2021 15:00:09 +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 C67FB9AAD for ; Sun, 11 Apr 2021 17:00:08 +0200 (CEST) Received: from localhost ([::1]:33132 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1lVbZH-0003yf-Qj for larch@yhetil.org; Sun, 11 Apr 2021 11:00:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:48502) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1lVbZC-0003x9-FD for guix-patches@gnu.org; Sun, 11 Apr 2021 11:00:02 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:44174) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1lVbZC-00034h-6r for guix-patches@gnu.org; Sun, 11 Apr 2021 11:00:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1lVbZC-000731-44 for guix-patches@gnu.org; Sun, 11 Apr 2021 11:00:02 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#47709] [PATCH 2/2] doc: Document 'gnu-build-system' keyword parameters. Resent-From: Maxime Devos Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Sun, 11 Apr 2021 15:00:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 47709 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Ludovic =?UTF-8?Q?Court=C3=A8s?= , 47709@debbugs.gnu.org Received: via spool by 47709-submit@debbugs.gnu.org id=B47709.161815319427053 (code B ref 47709); Sun, 11 Apr 2021 15:00:02 +0000 Received: (at 47709) by debbugs.gnu.org; 11 Apr 2021 14:59:54 +0000 Received: from localhost ([127.0.0.1]:55720 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lVbZ4-00072H-0l for submit@debbugs.gnu.org; Sun, 11 Apr 2021 10:59:54 -0400 Received: from laurent.telenet-ops.be ([195.130.137.89]:57558) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1lVbZ1-000725-2X for 47709@debbugs.gnu.org; Sun, 11 Apr 2021 10:59:52 -0400 Received: from ptr-bvsjgyjmffd7q9timvx.18120a2.ip6.access.telenet.be ([IPv6:2a02:1811:8c09:9d00:aaf1:9810:a0b8:a55d]) by laurent.telenet-ops.be with bizsmtp id rSzo2400U0mfAB401Szo1h; Sun, 11 Apr 2021 16:59:49 +0200 Message-ID: <4d9dddc71c70c5449843989515f59ca71720f3f7.camel@telenet.be> From: Maxime Devos Date: Sun, 11 Apr 2021 16:59:40 +0200 In-Reply-To: <20210411134606.26449-2-ludo@gnu.org> References: <20210411134606.26449-1-ludo@gnu.org> <20210411134606.26449-2-ludo@gnu.org> Content-Type: multipart/signed; micalg="pgp-sha512"; protocol="application/pgp-signature"; boundary="=-gFcXnPzKx/0erTAz20rm" User-Agent: Evolution 3.34.2 MIME-Version: 1.0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=telenet.be; s=r21; t=1618153189; bh=6OU+V1IYE0x5IRhehcOoC6xutDbs1B8oEgoWZAhcU5E=; h=Subject:From:To:Date:In-Reply-To:References; b=gy/5kV8EYkQ7eFzZZ6idZ1tiI0zn5SploYoP+ZUKazE11NvSedYKYPzLGBDfZOdRr d6Yqygka1uZ8VklWYP0H+MVrfY+TWgyBH3Cw/SoF3Y7+39P8M7hpQM5LHVWJyzUi2L Uqp5EW9Na0POzZnauZ8Wpv30W5DJyhxLqBxIprmsrlV0L+wXU1Qd/SCEQCvo9l6OXh HEAupQO614m+0zYAVVPr53of7sRgvxbP6ixeUrbVffLgzQcqdTZPS1EzvzFBOR2RQ1 Ci1w7N9JI6zk3O5fdXno7caqjFVafQrKPvf9pWOU+6K3JN3BnW7eQChYmKpQPQF7MI bprT7qyDWkEVg== 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 ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1618153209; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:resent-cc:resent-from:resent-sender: resent-message-id:in-reply-to:in-reply-to:references:references: list-id:list-help:list-unsubscribe:list-subscribe:list-post: dkim-signature; bh=6OU+V1IYE0x5IRhehcOoC6xutDbs1B8oEgoWZAhcU5E=; b=JCTcrPaaIO7NH/EQK+DyTINEAXrWgQSU6WG3TUIag6uWFqQSmE8g1Vr/C/HicJ/8zxDpTZ j4QgHD/z5KqQR6O5v4BE6YldZBvPIX3HgjzrhW1cCaAd4TzUXN1wuzgmslt5Hha+44Dtdr K+Dk6xTxpPsGbgYMzj1YkD6z5KI/B+f0eCQafqhvbl6+VEkOAdrtGCg1Zz0Cx/aK/A24J9 jInXnZjV47NudAdHcld3fVC9dgE685RulkredUYb/AEnT6+augNKkgyUgGQf06fU4yJVAb DVq5lyZzXRcOTMjjlVDkSeKq+uV3GRBv657DSoAUnSiF8fAiId1yat0c40kYAQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1618153209; a=rsa-sha256; cv=none; b=l9rS4S0aol3/V7MWzPiIY9aMXXiGfcgRyXhcYbuNq4/ytBIzx9pzT+6hfDTQQFzadVc4so 7az6KXDij22z5NFje8m0MCbFvHkBiN7jHU0TAeez+R2uoumxvyBzK5gzL6jGPCas5FYUb7 ngXYTd5GgvaPL+WldFA3K9OdaQZNnYiej3DPMyGEoRlMfHvxsbFeZYG0Vj/mtitzPrZqVx XEzjmN1LE5obLii/GMOm8a+lqZSjytboH5z0z0fvvv7zXSTbC9jW8GvZbBQR5EtdGoMUHz E03xkVtwpe0Wy53A0oYF8froYKV60Y5q47ZBnik48c91QSyuz2s183SvxNOrcw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=telenet.be header.s=r21 header.b="gy/5kV8E"; dmarc=fail reason="SPF not aligned (relaxed)" header.from=telenet.be (policy=none); spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Spam-Score: -1.94 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=telenet.be header.s=r21 header.b="gy/5kV8E"; dmarc=fail reason="SPF not aligned (relaxed)" header.from=telenet.be (policy=none); spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Queue-Id: C67FB9AAD X-Spam-Score: -1.94 X-Migadu-Scanner: scn0.migadu.com X-TUID: 1+DElIfpcczT --=-gFcXnPzKx/0erTAz20rm Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Some small remarks: On Sun, 2021-04-11 at 15:46 +0200, Ludovic Court=C3=A8s wrote: >=20 > [...] > @@ -7307,6 +7307,84 @@ Coreutils, Bash, Make, Diffutils, grep, and sed (s= ee the @code{(guix > build-system gnu)} module for a complete list). We call these the > @dfn{implicit inputs} of a package, because package definitions do not > have to mention them. > + > +This build system supports a number of keyword arguments, which can be > +passed @i{via} Why the italics? I've heard some people italicise "via" because it's a for= eign word (from Latin), but I'm not convinced. I don't see anyone italicising "broccoli", even though it is Italian (going by https://en.wiktionary.org/wiki/broccoli). > the @code{arguments} field of a package. Here are some > +of the main parameters: > + > +@table @code > +@item #:phases > +This argument specifies build-side code that evaluates to an alist of > +build phases. @xref{Build Phases}, for more information. > + > +@item #:configure-flags > +This is a list of flags (strings) passed to the @command{configure} > +script. @xref{Defining Packages}, for an example. > + > +@item #:make-flags > +This list of strings contains flags passed as arguments to > +@command{make} invocations in the @code{build}, @code{check}, and > +@code{install} phases. > + > +@item #:out-of-source? > +This Boolean, =E2=80=98Boolean=E2=80=99 is miscapitalised. > @code{#f} by default, indicates whether to run builds in a > +build directory separate from the source tree. > + > +When it is true, the @code{configure} phase creates a separate build > +directory, changes to that directory, and runs the @code{configure} > +script from there. This is useful for packages that require it, such as > +@code{glibc}. > + > +@item #:tests? > +This Boolean, @code{#t} by default, indicates whether the @code{check} > +phase should run the package's test suite. Likewise (miscapitalised). > +@item #:test-target > +This string, @code{"check"} by default, gives the name of the makefile > +target used by the @code{check} phase. > + > +@item #:parallel-build? > +@itemx #:parallel-tests? > +These Boolean values specify whether to build, respectively run the test Likewise (miscapitalised). > +suite, in parallel, with the @code{-j} flag of @command{make}. When > +they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is > +the number specified as the @option{--cores} option of > +@command{guix-daemon} or that of the @command{guix} client command > +(@pxref{Common Build Options, @option{--cores}}). > + > +@cindex RUNPATH, validation > +@item #:validate-runpath? > +This Boolean, @code{#t} by default, determines whether to ``validate'' Likewise (miscapitalised). > +the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well > +as executables) previously installed by the @code{install} phase. > + > +This validation step consists in making sure that all the shared > +libraries needed by an ELF binaries, which are listed as > +@code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the > +@code{DT_RUNPATH} entry of that binary. In other words, it ensures that > +running or using those binaries will not result in a ``file not found'' > +error at run time. @xref{Options, @option{-rpath},, ld, The GNU > +Linker}, for more information on @code{RUNPATH}. > + > +@item #:substitutable? > +This Boolean, @code{#t} by default, tells whether the package outputs Likewise (miscapitalised). > +should be substitutable---i.e., whether users should be able to obtain > +substitutes for them instead of building locally (@pxref{Substitutes}). > + > +@item #:allowed-references > +@itemx #:disallowed-references > +When true, these arguments must be a list of dependencies that must not > +appear among the references of the build results. If, upon build > +completion, some of these references are retained, the build process > +fails. > + > +This is useful to ensure that a package does not erroneously keep a > +reference to some of it build-time inputs, in cases where doing so > +would, for example, unnecessarily increase its size (@pxref{Invoking > +guix size}). > +@end table > + > +Most other build systems support these keyword arguments. > @end defvr > =20 > Other @code{} objects are defined to support other No other remarks. LGTM Greetings, Maxime. --=-gFcXnPzKx/0erTAz20rm Content-Type: application/pgp-signature; name="signature.asc" Content-Description: This is a digitally signed message part Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYHMO3BccbWF4aW1lZGV2 b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7l/vAQD6euyas9Yxb6CdCdD8ChyzqDIU INaSe2G7MUYi28n5DQEA1waiiggnB+SBjddu/EoRqZ41BLxOIK+QMp/nh38CWAU= =RyBr -----END PGP SIGNATURE----- --=-gFcXnPzKx/0erTAz20rm--