09/10: doc: Document guix potluck.

[Andy Wingo]

wingo pushed a commit to branch wip-potluck
in repository guix.

commit 570a64b20700302fba2f6c0799137b54aa7497f9
Author: Andy Wingo <address@hidden>
Date:   Mon Apr 24 22:44:17 2017 +0200

    doc: Document guix potluck.
    
    * doc/guix.texi (potluck-package Reference):
    (Invoking guix potluck): New sections.
---
 doc/guix.texi | 231 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 231 insertions(+)

diff --git a/doc/guix.texi b/doc/guix.texi
index c0ffdfd..bc2a4d0 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -58,6 +58,7 @@ Documentation License''.
 * guix environment: (guix)Invoking guix environment. Building development 
environments with Guix.
 * guix build: (guix)Invoking guix build.      Building packages.
 * guix pack: (guix)Invoking guix pack.        Creating binary bundles.
+* guix potluck: (guix)Invoking guix potluck.  Publishing package definitions.
 @end direntry
 
 @titlepage
@@ -137,6 +138,7 @@ Defining Packages
 
 * package Reference::           The package data type.
 * origin Reference::            The origin data type.
+* potluck-package Reference::   The potluck-package data type.
 
 Utilities
 
@@ -154,6 +156,7 @@ Utilities
 * Invoking guix challenge::     Challenging substitute servers.
 * Invoking guix copy::          Copying to and from a remote store.
 * Invoking guix container::     Process isolation.
+* Invoking guix potluck::       Simple, decoupled package development.
 
 Invoking @command{guix build}
 
@@ -2978,6 +2981,7 @@ when @var{cut?} returns true for a given package.
 @menu
 * package Reference ::          The package data type.
 * origin Reference::            The origin data type.
+* potluck-package Reference::   The potluck-package data type.
 @end menu
 
 
@@ -3194,6 +3198,115 @@ this is @code{#f}, a sensible default is used.
 @end table
 @end deftp
 
address@hidden potluck-package Reference
address@hidden @code{potluck-package} Reference
+
+This section defines all the options available in @code{potluck-package}
+declarations.  @xref{Invoking guix potluck}, for more background and for
+information on how to work with potluck packages from the command-line
+interface.
+
address@hidden {Data Type} potluck-package
+This is the data type representing a potluck package recipe.
+
address@hidden @asis
address@hidden @code{name}
+The name of the package, as a string.
+
address@hidden @code{version}
+The version of the package, as a string.
+
address@hidden @code{source}
+An object telling how the source code for the package should be
+acquired.  This is a @code{potluck-source} object, which itself is its
+own data type:
+
address@hidden {Data Type} potluck-source
+This is the data type representing a potluck package's source code.
+
address@hidden @asis
address@hidden @code{git-uri}
+An object containing the URI of the source git repository.  Currently
+potluck packages all come from Git.  Use the ``normal'' Guix packages if
+you need to build from some other source.
+
address@hidden @code{git-commit}
+The given git commit for the source, for example as a sha1 string.
+
address@hidden @code{sha256}
+A bytevector containing the SHA-256 hash of the source, as a base32
+string.  Note that the explicit @code{base32} wrapper that is needed for
+normal Guix packages is not present in a potluck package source.
+
+You can obtain this information using @code{guix hash -g}
+(@pxref{Invoking guix hash}).
+
address@hidden @code{snippet} (default: @code{#f})
+An S-expression that will be run in the source directory.  This is a
+convenient way to modify the source, sometimes more convenient than a
+patch.
address@hidden table
address@hidden deftp
+
address@hidden @code{build-system}
+The build system that should be used to build the package, as a symbol.
+For example, @code{gnu}.  To list available build systems, use
address@hidden potluck init --build-system=help} (@pxref{Invoking guix
+potluck}).
+
address@hidden @code{arguments} (default: @code{'()})
+The arguments that should be passed to the build system.  This is a
+list, typically containing sequential keyword-value pairs, and is the
+same as for the @code{arguments} argument of a normal @code{package}
+object.
+
address@hidden @code{inputs} (default: @code{'()})
address@hidden @code{native-inputs} (default: @code{'()})
address@hidden @code{propagated-inputs} (default: @code{'()})
address@hidden inputs, of packages
+These fields list dependencies of the package.  Each item of an input
+list is a package specification string, for example @code{guile} or
address@hidden@@2.0} or, in the most specific form, @code{guile@@2.0:out}.
address@hidden with Multiple Outputs}, for more on package outputs.  For
+example, the list below specifies three inputs:
+
address@hidden
+'("libffi" "libunistring" "glib:bin")
address@hidden example
+
address@hidden cross compilation, package dependencies
+The distinction between @code{native-inputs} and @code{inputs} is
+necessary when considering cross-compilation.
+
address@hidden Reference}, for full details on the differences between
+these input types.
+
address@hidden @code{synopsis}
+A one-line description of the package.
+
address@hidden @code{description}
+A more elaborate description of the package.
+
address@hidden @code{license}
+The license of the package, as a symbol.  For example, @code{gpl3+}.  To
+list available build systems, use @code{guix potluck init
+--license=help} (@pxref{Invoking guix potluck}).
+
address@hidden @code{home-page}
+The URL to the home-page of the package, as a string.
+
address@hidden @code{location} (default: source location of the @code{package} 
form)
+The source location of the package.  It is useful to override this when
+inheriting from another package, in which case this field is not
+automatically corrected.
address@hidden table
address@hidden deftp
+
+As you can see, a potluck package is less elaborate than a normal Guix
+package.  If you find yourself needing more advanced features, probably
+your package should be a part of Guix proper.  But if not, a potluck
+package can often do the job.
+
 
 @node Build Systems
 @section Build Systems
@@ -4781,6 +4894,7 @@ the Scheme programming interface of Guix in a convenient 
way.
 * Invoking guix challenge::     Challenging substitute servers.
 * Invoking guix copy::          Copying to and from a remote store.
 * Invoking guix container::     Process isolation.
+* Invoking guix potluck::       Decoupled package definition.
 @end menu
 
 @node Invoking guix build
@@ -6999,6 +7113,123 @@ must be PID 1 of the container or one of its child 
processes.
 
 @end table
 
address@hidden Invoking guix potluck
address@hidden Invoking @command{guix potluck}
address@hidden potluck
address@hidden @command{guix potluck}
address@hidden Note
+As of version @value{VERSION}, this tool is experimental.  The interface
+is subject to radical change in the future.
address@hidden quotation
+
+Guix is developed as a unified project composed of both the package
+manager and the set of packages.  This allows Guix to evolve while
+remaining healthy and coherent.  If there is a change that needs to be
+done across Guix's entire tree, Guix developers can make it happen.  One
+way in which this principle manifests itself is in the @code{package}
+data type, where input packages are directly specified by value in the
address@hidden, @code{native-inputs}, and @code{propagated-inputs}
+fields, instead of being specified as some abstract package name and
+version constraint that Guix would have to solve for.  @xref{package
+Reference}, for more on the @code{package} data type.
+
+However it is sometimes desirable to develop a package or set of
+packages in a more decoupled way, for example when a package set is
+still incubating or when a package is inappropriate for sending upstream
+for some reason.  Such packages use Guix and extend Guix but are not a
+part of the Guix project, properly speaking.  As such, they need to be
+resilient to changes in upstream Guix.  It would be brittle if such a
+package definition had to reference a Guix package by value; the Scheme
+variable denoting the upstream Guix package might move to a different
+module, or be renamed, or changed in some unexpected way.
+
+Guix's @dfn{potluck} facility fills this gap.  A @dfn{potluck package}
+is like a normal Guix package, except it expresses its inputs in the
+form of package specifications instead of direct references.
address@hidden Reference}.  Potluck packages also have a simpler
+package structure with fewer fields; compared to normal Guix packages,
+they are less expressive but more isolated from details of upstream
+Guix.
+
+The user interface to potluck packages is concentrated in the
address@hidden potluck} command.  To begin, let's say you are a developer
+of the @code{foo} project, and you'd like to package @code{foo} for use
+in your Guix system and maybe also that of a friend.  You're not sure if
+you want to support it yet so you don't want to make a proper release,
+but there should be something in the middle between that and not
+packaging it at all.  You decide to give @code{guix potluck} a go.
+
+So in that git checkout, you run @code{guix potluck init @var{url}},
+where @var{url} is a publicly accessible git URL at which @code{foo} is
+hosted.  @code{guix potluck init} takes the following options:
+
address@hidden @code
address@hidden address@hidden
address@hidden --build-system=help
address@hidden --autotools
+Indicate that the package uses the build system named @var{sys}.  Pass
address@hidden as the build system to see available options.
address@hidden is like the common @code{--build-system=gnu}, but
+additionally indicating that an @code{autoreconf} step is needed before
+building.
address@hidden address@hidden
address@hidden --license=help
+Specify the license of the project.
address@hidden table
+
+Calling @code{guix potluck init} will result in the creation of a
address@hidden directory in your git checkout, containing a brief
+overview @code{README.md} file as well as a @code{foo.scm} potluck
+package definition.  @xref{potluck-package Reference}.  Just fill in the
+synopsis and description and add the inputs and you have the beginnings
+of a potluck package.
+
+You can try building your new package by running @code{guix build -f
+guix-potluck/foo.scm}.  Once that works, you can share the file with
+your friends and they can build your package too.
+
+Of course, it would be nice if you could share that package with the
+world.  And it would be nice if your potluck package definitions could
+augment the set of available packages and versions.  And it would be
+nice if your potluck package could serve as a first draft of a proper
+Guix package definition.  We agree completely!
+
+Guix's potluck facility also implements a kind of registry of potluck
+recipes, as if it were hosting an actual potluck.  This
address@hidden facility takes requests to add potluck packages and
+translates that into a git repository of all potluck packages, as well
+as a git repository of Guix packages compiled from those potluck
+packages.
+
+To inform a channel host of the presence of fresh tasty potluck dishes,
+run @code{guix potluck update @var{url} @var{branch}}.  @var{url} should
+be the URL of a git repository containing a @code{guix-potluck}
+directory, and @var{branch} is a ref in that repository.  By default,
+the request is made to add the package to the default
address@hidden host; pass @address@hidden to specify
+an alternate registry.
+
+Running @code{guix potluck update} will simply enqueue an update request
+on the server.  Visit @code{https://@var{host}/} in your browser to see
+the state of the work queue, and to see whether your package update
+actually succeeded.  If it does succeed, you should be able to check out
+the git repository conventionally hosted at
address@hidden://@var{host}/git/main.git}, add that checkout to your
address@hidden, and thereby have access to that package.  In
+the future this will be made easier with a @code{guix channel} facility,
+but for now you have to use @code{GUIX_PACKAGE_PATH} or similar.
address@hidden Packages}, for more information.
+
+Finally, there is the code that actually runs the potluck service:
address@hidden potluck host-channel}.  This tool will host a web server on
+localhost, listening on port 8080 by default.  It expects to be behind
+some kind of HTTPS terminator, like @code{nginx}.  It does the work of
+translating update requests to git repositories.  Guix includes an
+example operating system definition for a server combining HTTPS access
+to git repositories, an @code{nginx} web front-end, and a @code{guix
+potluck host-channel} instance.
+
+
 @c *********************************************************************
 @node GNU Distribution
 @chapter GNU Distribution