Newer
Older
@example
guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
@end example
This command lists the dependents of the ``final'' libc (essentially all
@item --update
@itemx -u
Update distribution source files (package recipes) in place. This is
usually run from a checkout of the Guix source tree (@pxref{Running
Guix Before It Is Installed}):
@example
$ ./pre-inst-env guix refresh -s non-core -u
@end example
@xref{Defining Packages}, for more information on package definitions.
@item --select=[@var{subset}]
@itemx -s @var{subset}
Select all the packages in @var{subset}, one of @code{core} or
@code{non-core}.
The @code{core} subset refers to all the packages at the core of the
distribution---i.e., packages that are used to build ``everything
else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
changing one of these packages in the distribution entails a rebuild of
all the others. Thus, such updates are an inconvenience to users in
terms of build time or bandwidth used to achieve the upgrade.
The @code{non-core} subset refers to the remaining packages. It is
typically useful in cases where an update of the core packages would be
inconvenient.
@item --manifest=@var{file}
@itemx -m @var{file}
Select all the packages from the manifest in @var{file}. This is useful to
check if any packages of the user manifest can be updated.
@item --type=@var{updater}
@itemx -t @var{updater}
Select only packages handled by @var{updater} (may be a comma-separated
list of updaters). Currently, @var{updater} may be one of:
@table @code
@item gnu
the updater for GNU packages;
@item gnome
the updater for GNOME packages;
@item kde
the updater for KDE packages;
@item xorg
the updater for X.org packages;
@item kernel.org
the updater for packages hosted on kernel.org;
@item elpa
the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
@item cran
the updater for @uref{https://cran.r-project.org/, CRAN} packages;
@item bioconductor
the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
@item cpan
the updater for @uref{https://www.cpan.org/, CPAN} packages;
@item pypi
the updater for @uref{https://pypi.python.org, PyPI} packages.
@item gem
the updater for @uref{https://rubygems.org, RubyGems} packages.
@item github
the updater for @uref{https://github.com, GitHub} packages.
@item hackage
the updater for @uref{https://hackage.haskell.org, Hackage} packages.
@item stackage
the updater for @uref{https://www.stackage.org, Stackage} packages.
@item crate
the updater for @uref{https://crates.io, Crates} packages.
@item launchpad
the updater for @uref{https://launchpad.net, Launchpad} packages.
@end table
For instance, the following command only checks for updates of Emacs
packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
$ guix refresh --type=elpa,cran
gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
@end table
In addition, @command{guix refresh} can be passed one or more package
names, as in this example:
$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
@noindent
The command above specifically updates the @code{emacs} and
@code{idutils} packages. The @option{--select} option would have no
When considering whether to upgrade a package, it is sometimes
convenient to know which packages would be affected by the upgrade and
should be checked for compatibility. For this the following option may
be used when passing @command{guix refresh} one or more package names:
@item --list-updaters
@itemx -L
List available updaters and exit (see @option{--type} above).
For each updater, display the fraction of packages it covers; at the
end, display the fraction of packages covered by all these updaters.
@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a
result of upgrading one or more packages.
@xref{Invoking guix graph, the @code{reverse-package} type of
@command{guix graph}}, for information on how to visualize the list of
dependents of a package.
Be aware that the @option{--list-dependent} option only
@emph{approximates} the rebuilds that would be required as a result of
an upgrade. More rebuilds might be required under some circumstances.
$ guix refresh --list-dependent flex
Building the following 120 packages would ensure 213 dependent packages are rebuilt:
hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
The command above lists a set of packages that could be built to check
for compatibility with an upgraded @code{flex} package.
@table @code
@item --list-transitive
List all the packages which one or more packages depend upon.
$ guix refresh --list-transitive flex
flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{}
The command above lists a set of packages which, when changed, would cause
@code{flex} to be rebuilt.
The following options can be used to customize GnuPG operation:
@item --gpg=@var{command}
Use @var{command} as the GnuPG 2.x command. @var{command} is searched
for in @code{$PATH}.
@item --keyring=@var{file}
Use @var{file} as the keyring for upstream keys. @var{file} must be in the
@dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx}
and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
information on a tool to manipulate keybox files).
When this option is omitted, @command{guix refresh} uses
@file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
signing keys. OpenPGP signatures are checked against keys from this keyring;
missing keys are downloaded to this keyring as well (see
You can export keys from your default GPG keyring into a keybox file using
commands like this one:
gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
Likewise, you can fetch keys to a specific keybox file like this:
gpg --no-default-keyring --keyring mykeyring.kbx \
--recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
Privacy Guard}, for more information on GPG's @option{--keyring} option.
@item --key-download=@var{policy}
Handle missing OpenPGP keys according to @var{policy}, which may be one
of:
@table @code
@item always
Always download missing OpenPGP keys from the key server, and add them
to the user's GnuPG keyring.
@item never
Never try to download missing OpenPGP keys. Instead just bail out.
@item interactive
When a package signed with an unknown OpenPGP key is encountered, ask
the user whether to download it or not. This is the default behavior.
@end table
@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.
@item --load-path=@var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).
This allows users to define their own packages and make them visible to
the command-line tools.
The @code{github} updater uses the
@uref{https://developer.github.com/v3/, GitHub API} to query for new
releases. When used repeatedly e.g.@: when refreshing all packages,
GitHub will eventually refuse to answer any further API requests. By
default 60 API requests per hour are allowed, and a full refresh on all
GitHub packages in Guix requires more than this. Authentication with
GitHub through the use of an API token alleviates these limits. To use
an API token, set the environment variable @env{GUIX_GITHUB_TOKEN} to a
token procured from @uref{https://github.com/settings/tokens} or
otherwise.
@node Invoking guix lint
@section Invoking @command{guix lint}
@cindex @command{guix lint}
@cindex package, checking for errors
The @command{guix lint} command is meant to help package developers avoid
common errors and use a consistent style. It runs a number of checks on
a given set of packages in order to find common mistakes in their
definitions. Available @dfn{checkers} include (see
@option{--list-checkers} for a complete list):
@table @code
@item synopsis
@itemx description
Validate certain typographical and stylistic rules about package
descriptions and synopses.
@item inputs-should-be-native
Identify inputs that should most likely be native inputs.
@item source
@itemx home-page
@itemx mirror-url
@itemx github-url
@itemx source-file-name
Probe @code{home-page} and @code{source} URLs and report those that are
invalid. Suggest a @code{mirror://} URL when applicable. If the
@code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
URL. Check that the source file name is meaningful, e.g.@: is not just a
version number or ``git-checkout'', without a declared @code{file-name}
(@pxref{origin Reference}).
@item source-unstable-tarball
Parse the @code{source} URL to determine if a tarball from GitHub is
autogenerated or if it is a release tarball. Unfortunately GitHub's
autogenerated tarballs are sometimes regenerated.
@item derivation
Check that the derivation of the given packages can be successfully
computed for all the supported systems (@pxref{Derivations}).
@item profile-collisions
Check whether installing the given packages in a profile would lead to
collisions. Collisions occur when several packages with the same name
but a different version or a different store file name are propagated.
@xref{package Reference, @code{propagated-inputs}}, for more information
on propagated inputs.
10286
10287
10288
10289
10290
10291
10292
10293
10294
10295
10296
10297
10298
10299
10300
10301
10302
10303
10304
10305
10306
10307
10308
10309
10310
@item archival
@cindex Software Heritage, source code archive
@cindex archival of source code, Software Heritage
Checks whether the package's source code is archived at
@uref{https://www.softwareheritage.org, Software Heritage}.
When the source code that is not archived comes from a version-control system
(VCS)---e.g., it's obtained with @code{git-fetch}, send Software Heritage a
``save'' request so that it eventually archives it. This ensures that the
source will remain available in the long term, and that Guix can fall back to
Software Heritage should the source code disappear from its original host.
The status of recent ``save'' requests can be
@uref{https://archive.softwareheritage.org/save/#requests, viewed on-line}.
When source code is a tarball obtained with @code{url-fetch}, simply print a
message when it is not archived. As of this writing, Software Heritage does
not allow requests to save arbitrary tarballs; we are working on ways to
ensure that non-VCS source code is also archived.
Software Heritage
@uref{https://archive.softwareheritage.org/api/#rate-limiting, limits the
request rate per IP address}. When the limit is reached, @command{guix lint}
prints a message and the @code{archival} checker stops doing anything until
that limit has been reset.
@item cve
@cindex security vulnerabilities
@cindex CVE, Common Vulnerabilities and Exposures
Report known vulnerabilities found in the Common Vulnerabilities and
Exposures (CVE) databases of the current and past year
@uref{https://nvd.nist.gov/vuln/data-feeds, published by the US
To view information about a particular vulnerability, visit pages such as:
@itemize
@item
@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
@item
@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
@end itemize
@noindent
where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
@code{CVE-2015-7554}.
Package developers can specify in package recipes the
@uref{https://nvd.nist.gov/products/cpe,Common Platform Enumeration (CPE)}
name and version of the package when they differ from the name or version
that Guix uses, as in this example:
(package
(name "grub")
;; @dots{}
;; CPE calls this package "grub2".
(properties '((cpe-name . "grub2")
@c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
Some entries in the CVE database do not specify which version of a
package they apply to, and would thus ``stick around'' forever. Package
developers who found CVE alerts and verified they can be ignored can
declare them as in this example:
(package
(name "t1lib")
;; @dots{}
;; These CVEs no longer apply and can be safely ignored.
(properties `((lint-hidden-cve . ("CVE-2011-0433"
"CVE-2011-1553"
"CVE-2011-1554"
"CVE-2011-5244")))))
@item formatting
Warn about obvious source code formatting issues: trailing white space,
use of tabulations, etc.
guix lint @var{options} @var{package}@dots{}
If no package is given on the command line, then all packages are checked.
The @var{options} may be zero or more of the following:
@table @code
@item --list-checkers
@itemx -l
List and describe all the available checkers that will be run on packages
and exit.
@item --checkers
@itemx -c
Only enable the checkers specified in a comma-separated list using the
names returned by @option{--list-checkers}.
@item --load-path=@var{directory}
@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).
This allows users to define their own packages and make them visible to
the command-line tools.
@node Invoking guix size
@section Invoking @command{guix size}
@cindex size
@cindex package size
@cindex closure
@cindex @command{guix size}
The @command{guix size} command helps package developers profile the
disk usage of packages. It is easy to overlook the impact of an
additional dependency added to a package, or the impact of using a
single output for a package that could easily be split (@pxref{Packages
with Multiple Outputs}). Such are the typical issues that
@command{guix size} can highlight.
The command can be passed one or more package specifications
such as @code{gcc@@4.8}
or @code{guile:debug}, or a file name in the store. Consider this
example:
$ guix size coreutils
store item total self
/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
total: 78.9 MiB
@cindex closure
The store items listed here constitute the @dfn{transitive closure} of
Coreutils---i.e., Coreutils and all its dependencies, recursively---as
would be returned by:
@example
$ guix gc -R /gnu/store/@dots{}-coreutils-8.23
@end example
Here the output shows three columns next to store items. The first column,
labeled ``total'', shows the size in mebibytes (MiB) of the closure of
the store item---that is, its own size plus the size of all its
dependencies. The next column, labeled ``self'', shows the size of the
item itself. The last column shows the ratio of the size of the item
itself to the space occupied by all the items listed here.
In this example, we see that the closure of Coreutils weighs in at
79@tie{}MiB, most of which is taken by libc and GCC's run-time support
libraries. (That libc and GCC's libraries represent a large fraction of
the closure is not a problem @i{per se} because they are always available
on the system anyway.)
Since the command also accepts store file names, assessing the size of
a build result is straightforward:
@example
guix size $(guix system build config.scm)
@end example
When the package(s) passed to @command{guix size} are available in the
store@footnote{More precisely, @command{guix size} looks for the
@emph{ungrafted} variant of the given package(s), as returned by
@code{guix build @var{package} --no-grafts}. @xref{Security Updates},
for information on grafts.}, @command{guix size} queries the daemon to determine its
dependencies, and measures its size in the store, similar to @command{du
-ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
Coreutils}).
When the given packages are @emph{not} in the store, @command{guix size}
reports information based on the available substitutes
(@pxref{Substitutes}). This makes it possible it to profile disk usage of
store items that are not even on disk, only available remotely.
You can also specify several package names:
$ guix size coreutils grep sed bash
store item total self
/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
@dots{}
total: 102.3 MiB
@noindent
In this example we see that the combination of the four packages takes
102.3@tie{}MiB in total, which is much less than the sum of each closure
since they have a lot of dependencies in common.
When looking at the profile returned by @command{guix size}, you may
find yourself wondering why a given package shows up in the profile at
all. To understand it, you can use @command{guix graph --path -t
references} to display the shortest path between the two packages
(@pxref{Invoking guix graph}).
@item --substitute-urls=@var{urls}
Use substitute information from @var{urls}.
@xref{client-substitute-urls, the same option for @code{guix build}}.
@item --sort=@var{key}
Sort lines according to @var{key}, one of the following options:
@table @code
@item self
the size of each item (the default);
@item closure
the total size of the item's closure.
@end table
@item --map-file=@var{file}
Write a graphical map of disk usage in PNG format to @var{file}.
For the example above, the map looks like this:
@image{images/coreutils-size-map,5in,, map of Coreutils disk usage
produced by @command{guix size}}
@uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
installed and visible in Guile's module search path. When that is not
the case, @command{guix size} fails as it tries to load it.
@item --system=@var{system}
@itemx -s @var{system}
Consider packages for @var{system}---e.g., @code{x86_64-linux}.
@item --load-path=@var{directory}
@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).
This allows users to define their own packages and make them visible to
the command-line tools.
@node Invoking guix graph
@section Invoking @command{guix graph}
@cindex DAG
@cindex @command{guix graph}
@cindex package dependencies
Packages and their dependencies form a @dfn{graph}, specifically a
directed acyclic graph (DAG). It can quickly become difficult to have a
mental model of the package DAG, so the @command{guix graph} command
provides a visual representation of the DAG. By default,
@command{guix graph} emits a DAG representation in the input format of
@uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
directly to the @command{dot} command of Graphviz. It can also emit an
HTML page with embedded JavaScript code to display a ``chord diagram''
in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
emit Cypher queries to construct a graph in a graph database supporting
the @uref{https://www.opencypher.org/, openCypher} query language. With
@option{--path}, it simply displays the shortest path between two
packages. The general syntax is:
@example
guix graph @var{options} @var{package}@dots{}
@end example
For example, the following command generates a PDF file representing the
package DAG for the GNU@tie{}Core Utilities, showing its build-time
dependencies:
guix graph coreutils | dot -Tpdf > dag.pdf
@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
You may find it more pleasant to navigate the graph interactively with
@command{xdot} (from the @code{xdot} package):
@example
guix graph coreutils | xdot -
@end example
But there is more than one graph! The one above is concise: it is the
graph of package objects, omitting implicit inputs such as GCC, libc,
grep, etc. It is often useful to have such a concise graph, but
sometimes one may want to see more details. @command{guix graph} supports
several types of graphs, allowing you to choose the level of detail:
@table @code
@item package
This is the default type used in the example above. It shows the DAG of
package objects, excluding implicit dependencies. It is concise, but
filters out many details.
@item reverse-package
This shows the @emph{reverse} DAG of packages. For example:
guix graph --type=reverse-package ocaml
...@: yields the graph of packages that @emph{explicitly} depend on OCaml (if
you are also interested in cases where OCaml is an implicit dependency, see
Note that for core packages this can yield huge graphs. If all you want
is to know the number of packages that depend on a given package, use
@command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
@option{--list-dependent}}).
@item bag-emerged
This is the package DAG, @emph{including} implicit inputs.
For instance, the following command:
@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
At the bottom of the graph, we see all the implicit inputs of
@var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
Now, note that the dependencies of these implicit inputs---that is, the
@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
here, for conciseness.
@item bag
Similar to @code{bag-emerged}, but this time including all the bootstrap
dependencies.
@item bag-with-origins
Similar to @code{bag}, but also showing origins and their dependencies.
@item reverse-bag
This shows the @emph{reverse} DAG of packages. Unlike @code{reverse-package},
it also takes implicit dependencies into account. For example:
@example
guix graph -t reverse-bag dune
@end example
@noindent
...@: yields the graph of all packages that depend on Dune, directly or
indirectly. Since Dune is an @emph{implicit} dependency of many packages
@i{via} @code{dune-build-system}, this shows a large number of packages,
whereas @code{reverse-package} would show very few if any.
@item derivation
This is the most detailed representation: It shows the DAG of
derivations (@pxref{Derivations}) and plain store items. Compared to
the above representation, many additional nodes are visible, including
build scripts, patches, Guile modules, etc.
For this type of graph, it is also possible to pass a @file{.drv} file
name instead of a package name, as in:
@example
guix graph -t derivation `guix system build -d my-config.scm`
@end example
@item module
This is the graph of @dfn{package modules} (@pxref{Package Modules}).
For example, the following command shows the graph for the package
module that defines the @code{guile} package:
@example
@end example
All the types above correspond to @emph{build-time dependencies}. The
following graph type represents the @emph{run-time dependencies}:
@table @code
@item references
This is the graph of @dfn{references} of a package output, as returned
by @command{guix gc --references} (@pxref{Invoking guix gc}).
If the given package output is not available in the store, @command{guix
graph} attempts to obtain dependency information from substitutes.
Here you can also pass a store file name instead of a package name. For
example, the command below produces the reference graph of your profile
(which can be big!):
@example
guix graph -t references `readlink -f ~/.guix-profile`
@end example
@item referrers
This is the graph of the @dfn{referrers} of a store item, as returned by
@command{guix gc --referrers} (@pxref{Invoking guix gc}).
This relies exclusively on local information from your store. For
instance, let us suppose that the current Inkscape is available in 10
profiles on your machine; @command{guix graph -t referrers inkscape}
will show a graph rooted at Inkscape and with those 10 profiles linked
to it.
It can help determine what is preventing a store item from being garbage
collected.
10713
10714
10715
10716
10717
10718
10719
10720
10721
10722
10723
10724
10725
10726
10727
10728
10729
10730
10731
10732
10733
10734
10735
@cindex shortest path, between packages
Often, the graph of the package you are interested in does not fit on
your screen, and anyway all you want to know is @emph{why} that package
actually depends on some seemingly unrelated package. The
@option{--path} option instructs @command{guix graph} to display the
shortest path between two packages (or derivations, or store items,
etc.):
@example
$ guix graph --path emacs libunistring
emacs@@26.3
mailutils@@3.9
libunistring@@0.9.10
$ guix graph --path -t derivation emacs libunistring
/gnu/store/@dots{}-emacs-26.3.drv
/gnu/store/@dots{}-mailutils-3.9.drv
/gnu/store/@dots{}-libunistring-0.9.10.drv
$ guix graph --path -t references emacs libunistring
/gnu/store/@dots{}-emacs-26.3
/gnu/store/@dots{}-libidn2-2.2.0
/gnu/store/@dots{}-libunistring-0.9.10
@end example
The available options are the following:
@table @option
@item --type=@var{type}
@itemx -t @var{type}
Produce a graph output of @var{type}, where @var{type} must be one of
the values listed above.
@item --list-types
List the supported graph types.
@item --backend=@var{backend}
@itemx -b @var{backend}
Produce a graph using the selected @var{backend}.
@item --list-backends
List the supported graph backends.
Currently, the available backends are Graphviz and d3.js.
@item --path
Display the shortest path between two nodes of the type specified by
@option{--type}. The example below shows the shortest path between
@code{libreoffice} and @code{llvm} according to the references of
@code{libreoffice}:
@example
$ guix graph --path -t references libreoffice llvm
/gnu/store/@dots{}-libreoffice-6.4.2.2
/gnu/store/@dots{}-libepoxy-1.5.4
/gnu/store/@dots{}-mesa-19.3.4
/gnu/store/@dots{}-llvm-9.0.1
@end example
@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.
This is useful to precisely refer to a package, as in this example:
@example
guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
@end example
@item --system=@var{system}
@itemx -s @var{system}
Display the graph for @var{system}---e.g., @code{i686-linux}.
The package dependency graph is largely architecture-independent, but there
are some architecture-dependent bits that this option allows you to visualize.
@item --load-path=@var{directory}
@itemx -L @var{directory}
Add @var{directory} to the front of the package module search path
(@pxref{Package Modules}).
This allows users to define their own packages and make them visible to
the command-line tools.
@end table
On top of that, @command{guix graph} supports all the usual package
transformation options (@pxref{Package Transformation Options}). This
makes it easy to view the effect of a graph-rewriting transformation
such as @option{--with-input}. For example, the command below outputs
the graph of @code{git} once @code{openssl} has been replaced by
@code{libressl} everywhere in the graph:
@example
guix graph git --with-input=openssl=libressl
@end example
So many possibilities, so much fun!
@node Invoking guix publish
@section Invoking @command{guix publish}
@cindex @command{guix publish}
The purpose of @command{guix publish} is to enable users to easily share
their store with others, who can then use it as a substitute server
(@pxref{Substitutes}).
When @command{guix publish} runs, it spawns an HTTP server which allows
anyone with network access to obtain substitutes from it. This means
that any machine running Guix can also act as if it were a build farm,
since the HTTP interface is compatible with Cuirass, the software behind
the @code{@value{SUBSTITUTE-SERVER}} build farm.
For security, each substitute is signed, allowing recipients to check
their authenticity and integrity (@pxref{Substitutes}). Because
@command{guix publish} uses the signing key of the system, which is only
readable by the system administrator, it must be started as root; the
@option{--user} option makes it drop root privileges early on.
The signing key pair must be generated before @command{guix publish} is
launched, using @command{guix archive --generate-key} (@pxref{Invoking
guix archive}).
The general syntax is:
guix publish @var{options}@dots{}
Running @command{guix publish} without any additional arguments will
spawn an HTTP server on port 8080:
guix publish
Once a publishing server has been authorized (@pxref{Invoking guix
archive}), the daemon may download substitutes from it:
@example
guix-daemon --substitute-urls=http://example.org:8080
@end example
By default, @command{guix publish} compresses archives on the fly as it
serves them. This ``on-the-fly'' mode is convenient in that it requires
no setup and is immediately available. However, when serving lots of
clients, we recommend using the @option{--cache} option, which enables
caching of the archives before they are sent to clients---see below for
details. The @command{guix weather} command provides a handy way to
check what a server provides (@pxref{Invoking guix weather}).
As a bonus, @command{guix publish} also serves as a content-addressed
mirror for source files referenced in @code{origin} records
(@pxref{origin Reference}). For instance, assuming @command{guix
publish} is running on @code{example.org}, the following URL returns the
raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
(represented in @code{nix-base32} format, @pxref{Invoking guix hash}):
@example
http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
@end example
Obviously, these URLs only work for files that are in the store; in
other cases, they return 404 (``Not Found'').
@cindex build logs, publication
Build logs are available from @code{/log} URLs like:
@example
http://example.org/log/gwspk@dots{}-guile-2.2.3
@end example
@noindent
When @command{guix-daemon} is configured to save compressed build logs,
as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
URLs return the compressed log as-is, with an appropriate
@code{Content-Type} and/or @code{Content-Encoding} header. We recommend
running @command{guix-daemon} with @option{--log-compression=gzip} since
Web browsers can automatically decompress it, which is not the case with
The following options are available:
@table @code
@item --port=@var{port}
@itemx -p @var{port}
Listen for HTTP requests on @var{port}.
@item --listen=@var{host}
Listen on the network interface for @var{host}. The default is to
accept connections from any interface.
@item --user=@var{user}
@itemx -u @var{user}
Change privileges to @var{user} as soon as possible---i.e., once the
server socket is open and the signing key has been read.
@item --compression[=@var{method}[:@var{level}]]
@itemx -C [@var{method}[:@var{level}]]
Compress data using the given @var{method} and @var{level}. @var{method} is
one of @code{lzip} and @code{gzip}; when @var{method} is omitted, @code{gzip}
is used.
When @var{level} is zero, disable compression. The range 1 to 9 corresponds
to different compression levels: 1 is the fastest, and 9 is the best
(CPU-intensive). The default is 3.
Usually, @code{lzip} compresses noticeably better than @code{gzip} for a small
increase in CPU usage; see
@uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip Web
page}.
Unless @option{--cache} is used, compression occurs on the fly and
the compressed streams are not
cached. Thus, to reduce load on the machine that runs @command{guix
publish}, it may be a good idea to choose a low compression level, to
run @command{guix publish} behind a caching proxy, or to use
@option{--cache}. Using @option{--cache} has the advantage that it
allows @command{guix publish} to add @code{Content-Length} HTTP header
to its responses.
This option can be repeated, in which case every substitute gets compressed
using all the selected methods, and all of them are advertised. This is
useful when users may not support all the compression methods: they can select
the one they support.
@item --cache=@var{directory}
@itemx -c @var{directory}
Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
and only serve archives that are in cache.
When this option is omitted, archives and meta-data are created
on-the-fly. This can reduce the available bandwidth, especially when
compression is enabled, since this may become CPU-bound. Another
drawback of the default mode is that the length of archives is not known
in advance, so @command{guix publish} does not add a
@code{Content-Length} HTTP header to its responses, which in turn
prevents clients from knowing the amount of data being downloaded.
Conversely, when @option{--cache} is used, the first request for a store
item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a
background process to @dfn{bake} the archive---computing its
@code{.narinfo} and compressing the archive, if needed. Once the
archive is cached in @var{directory}, subsequent requests succeed and
are served directly from the cache, which guarantees that clients get
the best possible bandwidth.
The ``baking'' process is performed by worker threads. By default, one
thread per CPU core is created, but this can be customized. See
@option{--workers} below.
When @option{--ttl} is used, cached entries are automatically deleted
when they have expired.
@item --workers=@var{N}
When @option{--cache} is used, request the allocation of @var{N} worker
threads to ``bake'' archives.
@item --ttl=@var{ttl}
Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
(TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
days, @code{1m} means 1 month, and so on.
This allows the user's Guix to keep substitute information in cache for
@var{ttl}. However, note that @code{guix publish} does not itself
guarantee that the store items it provides will indeed remain available
for as long as @var{ttl}.
Additionally, when @option{--cache} is used, cached entries that have
not been accessed for @var{ttl} and that no longer have a corresponding
item in the store, may be deleted.
@item --nar-path=@var{path}
Use @var{path} as the prefix for the URLs of ``nar'' files
(@pxref{Invoking guix archive, normalized archives}).
By default, nars are served at a URL such as
@code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to
change the @code{/nar} part to @var{path}.
@item --public-key=@var{file}
@itemx --private-key=@var{file}
Use the specific @var{file}s as the public/private key pair used to sign
the store items being published.
The files must correspond to the same key pair (the private key is used
for signing and the public key is merely advertised in the signature
metadata). They must contain keys in the canonical s-expression format
as produced by @command{guix archive --generate-key} (@pxref{Invoking
guix archive}). By default, @file{/etc/guix/signing-key.pub} and
@file{/etc/guix/signing-key.sec} are used.