futurile/guix-play
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: Distinguish the "nar bundle" format from "nar".

Browse Source 
* 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.
This commit is contained in:
Ludovic Courtès 2020-09-08 14:59:01 +02:00
parent 6310283bae
commit 7a68d3ccad
No known key found for this signature in database
GPG Key ID: 090B11993D9AEBB5
2 changed files with 19 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
doc/guix.texi
View File

@ -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

15
guix/nar.scm
View File

@ -1,5 +1,5 @@
;;; GNU Guix --- Functional package management for GNU
;;; Copyright © 2012, 2013, 2014, 2015, 2016, 2018, 2019 Ludovic Courtès <ludo@gnu.org>
;;; Copyright © 2012, 2013, 2014, 2015, 2016, 2018, 2019, 2020 Ludovic Courtès <ludo@gnu.org>
;;; Copyright © 2014 Mark H Weaver <mhw@netris.org>
;;;
;;; 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.