From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id aG44LeQCWF+sMAAA0tVLHw (envelope-from ) for ; Tue, 08 Sep 2020 22:17:08 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id aB4KKeQCWF9CPAAAB5/wlQ (envelope-from ) for ; Tue, 08 Sep 2020 22:17:08 +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 2CBD09404CA for ; Tue, 8 Sep 2020 22:17:08 +0000 (UTC) Received: from localhost ([::1]:60014 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kFlvH-0005Rj-4I for larch@yhetil.org; Tue, 08 Sep 2020 18:17:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:43430) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kFlvD-0005QO-HR for guix-patches@gnu.org; Tue, 08 Sep 2020 18:17:03 -0400 Received: from debbugs.gnu.org ([209.51.188.43]:45133) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1kFlvD-0004ZM-8Y for guix-patches@gnu.org; Tue, 08 Sep 2020 18:17:03 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1kFlvD-0002uG-41 for guix-patches@gnu.org; Tue, 08 Sep 2020 18:17:03 -0400 X-Loop: help-debbugs@gnu.org Subject: [bug#43285] [PATCH 2/3] doc: Distinguish the "nar bundle" format from "nar". Resent-From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Tue, 08 Sep 2020 22:17:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 43285 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 43285@debbugs.gnu.org Cc: Ludovic =?UTF-8?Q?Court=C3=A8s?= Received: via spool by 43285-submit@debbugs.gnu.org id=B43285.159960341910990 (code B ref 43285); Tue, 08 Sep 2020 22:17:03 +0000 Received: (at 43285) by debbugs.gnu.org; 8 Sep 2020 22:16:59 +0000 Received: from localhost ([127.0.0.1]:56676 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kFlv8-0002qo-O9 for submit@debbugs.gnu.org; Tue, 08 Sep 2020 18:16:59 -0400 Received: from eggs.gnu.org ([209.51.188.92]:33266) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1kFlv5-0002k8-9A for 43285@debbugs.gnu.org; Tue, 08 Sep 2020 18:16:57 -0400 Received: from fencepost.gnu.org ([2001:470:142:3::e]:50276) by eggs.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kFlv0-0004WV-3B; Tue, 08 Sep 2020 18:16:50 -0400 Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=54296 helo=gnu.org) by fencepost.gnu.org with esmtpsa (TLS1.2:DHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1kFluz-0008Ez-Aw; Tue, 08 Sep 2020 18:16:49 -0400 From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Date: Wed, 9 Sep 2020 00:16:34 +0200 Message-Id: <20200908221635.32684-2-ludo@gnu.org> X-Mailer: git-send-email 2.28.0 In-Reply-To: <20200908221635.32684-1-ludo@gnu.org> References: <20200908221635.32684-1-ludo@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Spam-Score: -2.3 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-Spam-Score: -3.3 (---) 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-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=none; dmarc=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-Spam-Score: -0.01 X-TUID: qLLGwu6BGABc * doc/guix.texi (Invoking guix archive): Introduce the term "nar bundle" and clarify what the output of "guix archive --export" really is. * guix/nar.scm (restore-one-item, restore-file-set): Use the term "nar bundle" in docstrings. --- doc/guix.texi | 12 +++++++++++- guix/nar.scm | 15 ++++++++------- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 1d6782e6fa..5cb4fe2dfd 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -4990,7 +4990,13 @@ what you should use in this case (@pxref{Invoking guix copy}). @cindex nar, archive format @cindex normalized archive (nar) -Archives are stored in the ``normalized archive'' or ``nar'' format, which is +@cindex nar bundle, archive format +Each store item is written in the @dfn{normalized archive} or @dfn{nar} +format (described below), and the output of @command{guix archive +--export} (and input of @command{guix archive --import}) is a @dfn{nar +bundle}. + +The nar format is comparable in spirit to `tar', but with differences that make it more appropriate for our purposes. First, rather than recording all Unix metadata for each file, the nar format only mentions @@ -5000,6 +5006,10 @@ entries are stored always follows the order of file names according to the C locale collation order. This makes archive production fully deterministic. +That nar bundle format is essentially the concatenation of zero or more +nars along with metadata for each store item it contains: its file name, +references, corresponding derivation, and a digital signature. + When exporting, the daemon digitally signs the contents of the archive, and that digital signature is appended. When importing, the daemon verifies the signature and rejects the import in case of an invalid diff --git a/guix/nar.scm b/guix/nar.scm index 6bb2ea5b96..a23af2e5de 100644 --- a/guix/nar.scm +++ b/guix/nar.scm @@ -1,5 +1,5 @@ ;;; GNU Guix --- Functional package management for GNU -;;; Copyright © 2012, 2013, 2014, 2015, 2016, 2018, 2019 Ludovic Courtès +;;; Copyright © 2012, 2013, 2014, 2015, 2016, 2018, 2019, 2020 Ludovic Courtès ;;; Copyright © 2014 Mark H Weaver ;;; ;;; This file is part of GNU Guix. @@ -156,7 +156,8 @@ protected from GC." (define* (restore-one-item port #:key acl (verify-signature? #t) (lock? #t) (log-port (current-error-port))) - "Restore one store item from PORT; return its file name on success." + "Restore one store item of a nar bundle read from PORT; return its file name +on success." (define (assert-valid-signature signature hash file) ;; Bail out if SIGNATURE, which must be a string as produced by @@ -251,11 +252,11 @@ a signature")) (define* (restore-file-set port #:key (verify-signature? #t) (lock? #t) (log-port (current-error-port))) - "Restore the file set read from PORT to the store. The format of the data -on PORT must be as created by 'export-paths'---i.e., a series of Nar-formatted -archives with interspersed meta-data joining them together, possibly with a -digital signature at the end. Log progress to LOG-PORT. Return the list of -files restored. + "Restore the file set (\"nar bundle\") read from PORT to the store. The +format of the data on PORT must be as created by 'export-paths'---i.e., a +series of Nar-formatted archives with interspersed meta-data joining them +together, possibly with a digital signature at the end. Log progress to +LOG-PORT. Return the list of files restored. When LOCK? is #f, assume locks for the files to be restored are already held. This is the case when the daemon calls a build hook. -- 2.28.0