From e74ca543b1b782d36f4283716d0e20bb877aa67d Mon Sep 17 00:00:00 2001 From: Maxime Devos Date: Thu, 25 Feb 2021 18:15:06 +0100 Subject: [PATCH 2/4] doc: Document how to define new substituters. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TODO the makefile should probably be adjusted, to allow translation of doc/substituters.texi and to include it in the release archive. * doc/guix.texi: Include the new section ‘Defining Substituters’ from ‘doc/substituters.texi’. * doc/substituters.texi: New file, documenting how to define new substituters. --- doc/guix.texi | 5 ++++ doc/substituters.texi | 56 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 61 insertions(+) create mode 100644 doc/substituters.texi diff --git a/doc/guix.texi b/doc/guix.texi index 27083f1ae6..591dc320d8 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -86,6 +86,7 @@ Copyright @copyright{} 2020 raingloom@* Copyright @copyright{} 2020 Daniel Brooks@* Copyright @copyright{} 2020 John Soo@* Copyright @copyright{} 2020 Jonathan Brielmaier@* +Copyright @copyright{} 2021 Maxime Devos@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -267,6 +268,7 @@ Programming Interface * The Store Monad:: Purely functional interface to the store. * G-Expressions:: Manipulating build expressions. * Invoking guix repl:: Programming Guix in Guile. +* Defining Substituters:: Defining new substitution methods. Defining Packages @@ -6361,6 +6363,7 @@ package definitions. * The Store Monad:: Purely functional interface to the store. * G-Expressions:: Manipulating build expressions. * Invoking guix repl:: Programming Guix in Guile +* Defining Substituters:: Defining new substitution methods. @end menu @node Package Modules @@ -10022,6 +10025,8 @@ Inhibit loading of the @file{~/.guile} file. By default, that configuration file is loaded when spawning a @code{guile} REPL. @end table +@include substituters.texi + @c ********************************************************************* @node Utilities @chapter Utilities diff --git a/doc/substituters.texi b/doc/substituters.texi new file mode 100644 index 0000000000..f86a1cb26c --- /dev/null +++ b/doc/substituters.texi @@ -0,0 +1,56 @@ +@node Defining Substituters +@section Defining Substituters + +@cindex substitutes, implementation +Guix currently only supports downloading substitutes via the HTTP and +HTTPS protocols, and substitutes over IPFS and GNUnet are planned. +An implementation of substitutes over some protocol is called a +‘substituter’. + +The API described here is implemented by the @code{(guix scripts substitute)} +module. In order to let the daemon actually find the substituter, the +substituter should be defined in a module @code{(guix scripts substitute name)}, +as a variable @var{name}-substituter. + +@c TODO currently unimplemented +@c +@c The @code{substitute-methods} daemon option must also be set to a +@c space-separated list of the names of the substituters to use. This is +@c currently unimplemented. + +@deffn {Scheme Procedure} make-substituter @var{name} @var{nar-downloader} @ + @var{fetch-narinfos} @var{recognised-uri-schemes} +Return a substituter for the protocols in @var{recognised-uri-schemes}, +a list of URI schemes. @var{fetch-narinfos} will be used finding narinfos +and @var{nar-downloader} to download a substitute. + +The procedure @var{nar-downloader} must be a keyword procedure +(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU +Guile Reference Manual}). It accepts two positional arguments +@var{destination} and @var{narinfo}. @var{destination} is the location +in the file system where the store item should be written to, +and @var{narinfo} is the narinfo describing the substitute to download. + +It should return @code{#f} if the substitute is not available +via this method. If the substitute was available, it should either +return an input port to read the nar from. + +@c TODO currently unimplemented, but will be used by the IPFS substituter: +@c or the symbol @code{unpacked} +@c if the substituter wrote the store item to @var{destination} by itself. + +The procedure @var{fetch-narinfos} must accept two arguments +@var{url} and @var{paths}, where @var{url} is the URL (as a string) +of a substitute server and @var{paths} is a list of store item names +for which to find a narinfo. + +This procedure should return a list of narinfos pertaining to +@var{paths} (possibly empty). It can be assumed @var{url} +has an URI scheme in @var{recognised-uri-schemes}. + +A substituter does not have to verify whether the narinfo and nar +are correctly signed and have a correct hash; this is handled +by @code{(guix scripts substitute)}. @var{nar-downloader} and +@var{fetch-narinfos} can be @code{#f} if unimplemented by this +substituter. +@end deffn -- 2.30.0