Newer
Older
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.
@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.
@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}
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
@code{reverse-bag} below.)
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:
guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
@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
guix graph -t module guile | dot -Tpdf > module-graph.pdf
@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.
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 --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
@code{--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 @code{--log-compression=gzip} since
Web browsers can automatically decompress it, which is not the case with
bzip2 compression.
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.
@item --repl[=@var{port}]
@itemx -r [@var{port}]
Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
Reference Manual}) on @var{port} (37146 by default). This is used
primarily for debugging a running @command{guix publish} server.
@end table
Enabling @command{guix publish} on Guix System is a one-liner: just
instantiate a @code{guix-publish-service-type} service in the @code{services} field
of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
@code{guix-publish-service-type}}).
If you are instead running Guix on a ``foreign distro'', follow these
@itemize
@item
If your host distro uses the systemd init system:
# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
/etc/systemd/system/
# systemctl start guix-publish && systemctl enable guix-publish
@end example
@item
If your host distro uses the Upstart init system:
# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
# start guix-publish
@end example
@item
Otherwise, proceed similarly with your distro's init system.
@end itemize
@node Invoking guix challenge
@section Invoking @command{guix challenge}
@cindex reproducible builds
@cindex verifiable builds
@cindex @command{guix challenge}
@cindex challenge
Do the binaries provided by this server really correspond to the source
code it claims to build? Is a package build process deterministic?
These are the questions the @command{guix challenge} command attempts to
answer.
The former is obviously an important question: Before using a substitute
server (@pxref{Substitutes}), one had better @emph{verify} that it
provides the right binaries, and thus @emph{challenge} it. The latter
is what enables the former: If package builds are deterministic, then
independent builds of the package should yield the exact same result,
bit for bit; if a server provides a binary different from the one
obtained locally, it may be either corrupt or malicious.
We know that the hash that shows up in @file{/gnu/store} file names is
the hash of all the inputs of the process that built the file or
directory---compilers, libraries, build scripts,
etc. (@pxref{Introduction}). Assuming deterministic build processes,
one store file name should map to exactly one build output.
@command{guix challenge} checks whether there is, indeed, a single
mapping by comparing the build outputs of several independent builds of
any given store item.
The command output looks like this:
@smallexample
$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0%
updating list of substitutes from 'https://guix.example.org'... 100.0%
/gnu/store/@dots{}-openssl-1.0.2d contents differ:
local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
differing files:
/lib/libcrypto.so.1.1
/lib/libssl.so.1.1
/gnu/store/@dots{}-git-2.5.0 contents differ:
local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
differing file:
/libexec/git-core/git-fsck
/gnu/store/@dots{}-pius-2.1.1 contents differ:
local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
differing file:
/share/man/man1/pius.1.gz
6,406 store items were analyzed:
- 4,749 (74.1%) were identical
- 525 (8.2%) differed
- 1,132 (17.7%) were inconclusive
@end smallexample
@noindent
In this example, @command{guix challenge} first scans the store to
determine the set of locally-built derivations---as opposed to store
items that were downloaded from a substitute server---and then queries
all the substitute servers. It then reports those store items for which
the servers obtained a result different from the local build.
@cindex non-determinism, in package builds
As an example, @code{guix.example.org} always gets a different answer.
Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, except in the
case of Git. This might indicate that the build process of Git is
non-deterministic, meaning that its output varies as a function of
various things that Guix does not fully control, in spite of building
packages in isolated environments (@pxref{Features}). Most common
sources of non-determinism include the addition of timestamps in build
results, the inclusion of random numbers, and directory listings sorted
by inode number. See @uref{https://reproducible-builds.org/docs/}, for
more information.
To find out what is wrong with this Git binary, the easiest approach is
to run:
@example
guix challenge git \
--diff=diffoscope \
--substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org"
@end example
This automatically invokes @command{diffoscope}, which displays detailed
information about files that differ.
Alternately, we can do something along these lines (@pxref{Invoking guix
archive}):
$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-git-2.5.0 \
| lzip -d | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
This command shows the difference between the files resulting from the
local build, and the files resulting from the build on
@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging Files,,
diffutils, Comparing and Merging Files}). The @command{diff} command
works great for text files. When binary files differ, a better option
is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
visualize differences for all kinds of files.
Once you have done that work, you can tell whether the differences are due
to a non-deterministic build process or to a malicious server. We try
hard to remove sources of non-determinism in packages to make it easier
to verify substitutes, but of course, this is a process that
involves not just Guix, but a large part of the free software community.
In the meantime, @command{guix challenge} is one tool to help address
the problem.
If you are writing packages for Guix, you are encouraged to check
whether @code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the
same build result as you did with:
$ guix challenge @var{package}
@end example
@noindent
where @var{package} is a package specification such as
@code{guile@@2.0} or @code{glibc:debug}.
The general syntax is:
guix challenge @var{options} [@var{packages}@dots{}]
When a difference is found between the hash of a locally-built item and
that of a server-provided substitute, or among substitutes provided by
different servers, the command displays it as in the example above and
its exit code is 2 (other non-zero exit codes denote other kinds of
errors.)
The one option that matters is:
@table @code
@item --substitute-urls=@var{urls}
Consider @var{urls} the whitespace-separated list of substitute source
URLs to compare to.
@item --diff=@var{mode}
Upon mismatches, show differences according to @var{mode}, one of:
@table @asis
@item @code{simple} (the default)
Show the list of files that differ.
@item @code{diffoscope}
@itemx @var{command}
Invoke @uref{https://diffoscope.org/, Diffoscope}, passing it
two directories whose contents do not match.
When @var{command} is an absolute file name, run @var{command} instead
of Diffoscope.
@item @code{none}
Do not show further details about the differences.
@end table
Thus, unless @code{--diff=none} is passed, @command{guix challenge}
downloads the store items from the given substitute servers so that it
can compare them.
@item --verbose
@itemx -v
Show details about matches (identical contents) in addition to
information about mismatches.
@end table
@node Invoking guix copy
@section Invoking @command{guix copy}
@cindex copy, of store items, over SSH
@cindex SSH, copy of store items
@cindex sharing store items across machines
@cindex transferring store items across machines
The @command{guix copy} command copies items from the store of one
machine to that of another machine over a secure shell (SSH)
connection@footnote{This command is available only when Guile-SSH was
found. @xref{Requirements}, for details.}. For example, the following
command copies the @code{coreutils} package, the user's profile, and all
their dependencies over to @var{host}, logged in as @var{user}:
guix copy --to=@var{user}@@@var{host} \
coreutils `readlink -f ~/.guix-profile`
If some of the items to be copied are already present on @var{host},
they are not actually sent.
The command below retrieves @code{libreoffice} and @code{gimp} from
@var{host}, assuming they are available there:
guix copy --from=@var{host} libreoffice gimp
The SSH connection is established using the Guile-SSH client, which is
compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
@file{~/.ssh/config}, and uses the SSH agent for authentication.
The key used to sign items that are sent must be accepted by the remote
machine. Likewise, the key used by the remote machine to sign items you
are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
own daemon. @xref{Invoking guix archive}, for more information about
store item authentication.
The general syntax is:
guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
You must always specify one of the following options:
@table @code
@item --to=@var{spec}
@itemx --from=@var{spec}
Specify the host to send to or receive from. @var{spec} must be an SSH
spec such as @code{example.org}, @code{charlie@@example.org}, or
@code{charlie@@example.org:2222}.
@end table
The @var{items} can be either package names, such as @code{gimp}, or
store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
When specifying the name of a package to send, it is first built if
needed, unless @option{--dry-run} was specified. Common build options
are supported (@pxref{Common Build Options}).
@node Invoking guix container
@section Invoking @command{guix container}
@cindex container
@cindex @command{guix container}
@quotation Note
As of version @value{VERSION}, this tool is experimental. The interface
is subject to radical change in the future.
@end quotation
The purpose of @command{guix container} is to manipulate processes
running within an isolated environment, commonly known as a
``container'', typically created by the @command{guix environment}
(@pxref{Invoking guix environment}) and @command{guix system container}
(@pxref{Invoking guix system}) commands.
The general syntax is:
guix container @var{action} @var{options}@dots{}
@var{action} specifies the operation to perform with a container, and
@var{options} specifies the context-specific arguments for the action.
The following actions are available:
@table @code
@item exec
Execute a command within the context of a running container.
The syntax is:
guix container exec @var{pid} @var{program} @var{arguments}@dots{}
@end example
@var{pid} specifies the process ID of the running container.
@var{program} specifies an executable file name within the root file
system of the container. @var{arguments} are the additional options that
will be passed to @var{program}.
The following command launches an interactive login shell inside a
Guix system container, started by @command{guix system container}, and whose
process ID is 9001:
guix container exec 9001 /run/current-system/profile/bin/bash --login
Note that the @var{pid} cannot be the parent process of a container. It
must be PID 1 of the container or one of its child processes.
@end table
@node Invoking guix weather
@section Invoking @command{guix weather}
Occasionally you're grumpy because substitutes are lacking and you end
up building packages by yourself (@pxref{Substitutes}). The
@command{guix weather} command reports on substitute availability on the
specified servers so you can have an idea of whether you'll be grumpy
today. It can sometimes be useful info as a user, but it is primarily
useful to people running @command{guix publish} (@pxref{Invoking guix
publish}).
@cindex statistics, for substitutes
@cindex availability of substitutes
@cindex substitute availability
@cindex weather, substitute availability
Here's a sample run:
$ guix weather --substitute-urls=https://guix.example.org
computing 5,872 package derivations for x86_64-linux...
looking for 6,128 store items on https://guix.example.org..
updating list of substitutes from 'https://guix.example.org'... 100.0%
https://guix.example.org
43.4% substitutes available (2,658 out of 6,128)
7,032.5 MiB of nars (compressed)
19,824.2 MiB on disk (uncompressed)
0.030 seconds per request (182.9 seconds in total)
33.5 requests per second
9.8% (342 out of 3,470) of the missing items are queued
867 queued builds
x86_64-linux: 518 (59.7%)
i686-linux: 221 (25.5%)
aarch64-linux: 128 (14.8%)
build rate: 23.41 builds per hour
x86_64-linux: 11.16 builds per hour
i686-linux: 6.03 builds per hour
aarch64-linux: 6.41 builds per hour
@end example
@cindex continuous integration, statistics
As you can see, it reports the fraction of all the packages for which
substitutes are available on the server---regardless of whether
substitutes are enabled, and regardless of whether this server's signing
key is authorized. It also reports the size of the compressed archives
(``nars'') provided by the server, the size the corresponding store
items occupy in the store (assuming deduplication is turned off), and
the server's throughput. The second part gives continuous integration
(CI) statistics, if the server supports it. In addition, using the
@option{--coverage} option, @command{guix weather} can list ``important''
package substitutes missing on the server (see below).
To achieve that, @command{guix weather} queries over HTTP(S) meta-data
(@dfn{narinfos}) for all the relevant store items. Like @command{guix
challenge}, it ignores signatures on those substitutes, which is
innocuous since the command only gathers statistics and cannot install
those substitutes.
The general syntax is:
@example
guix weather @var{options}@dots{} [@var{packages}@dots{}]
@end example
When @var{packages} is omitted, @command{guix weather} checks the availability
of substitutes for @emph{all} the packages, or for those specified with
@option{--manifest}; otherwise it only considers the specified packages. It
is also possible to query specific system types with @option{--system}.
@command{guix weather} exits with a non-zero code when the fraction of
available substitutes is below 100%.
The available options are listed below.
@table @code
@item --substitute-urls=@var{urls}
@var{urls} is the space-separated list of substitute server URLs to
query. When this option is omitted, the default set of substitute
servers is queried.
@item --system=@var{system}
@itemx -s @var{system}
Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
option can be repeated, in which case @command{guix weather} will query
substitutes for several system types.
@item --manifest=@var{file}
Instead of querying substitutes for all the packages, only ask for those
specified in @var{file}. @var{file} must contain a @dfn{manifest}, as
with the @code{-m} option of @command{guix package} (@pxref{Invoking
guix package}).
This option can be repeated several times, in which case the manifests
are concatenated.
@item --coverage[=@var{count}]
@itemx -c [@var{count}]
Report on substitute coverage for packages: list packages with at least
@var{count} dependents (zero by default) for which substitutes are
unavailable. Dependent packages themselves are not listed: if @var{b} depends
on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though
@var{b} usually lacks substitutes as well. The result looks like this:
@example
$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10
computing 8,983 package derivations for x86_64-linux...
looking for 9,343 store items on @value{SUBSTITUTE-URL}...
updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
@value{SUBSTITUTE-URL}
64.7% substitutes available (6,047 out of 9,343)
@dots{}
2502 packages are missing from '@value{SUBSTITUTE-URL}' for 'x86_64-linux', among which:
58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
@dots{}
@end example
What this example shows is that @code{kcoreaddons} and presumably the 58
packages that depend on it have no substitutes at @code{ci.guix.info};
likewise for @code{qgpgme} and the 46 packages that depend on it.
If you are a Guix developer, or if you are taking care of this build farm,
you'll probably want to have a closer look at these packages: they may simply
fail to build.
@item --display-missing
Display the list of store items for which substitutes are missing.
@end table
@node Invoking guix processes
@section Invoking @command{guix processes}
The @command{guix processes} command can be useful to developers and system
administrators, especially on multi-user machines and on build farms: it lists
the current sessions (connections to the daemon), as well as information about
the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
started with @option{--listen} specifying a TCP endpoint, are @emph{not}
listed.}. Here's an example of the information it returns:
$ sudo guix processes
SessionPID: 19002
ClientPID: 19090
ClientCommand: guix environment --ad-hoc python
SessionPID: 19402
ClientPID: 19367
ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
SessionPID: 19444
ClientPID: 19419
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800
ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800
ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800
@end example
In this example we see that @command{guix-daemon} has three clients:
@command{guix environment}, @command{guix publish}, and the Cuirass continuous
integration tool; their process identifier (PID) is given by the
@code{ClientPID} field. The @code{SessionPID} field gives the PID of the
@command{guix-daemon} sub-process of this particular session.
The @code{LockHeld} fields show which store items are currently locked by this
session, which corresponds to store items being built or substituted (the
@code{LockHeld} field is not displayed when @command{guix processes} is not
running as root.) Last, by looking at the @code{ChildProcess} field, we
understand that these three builds are being offloaded (@pxref{Daemon Offload
Setup}).
The output is in Recutils format so we can use the handy @command{recsel}
command to select sessions of interest (@pxref{Selection Expressions,,,
recutils, GNU recutils manual}). As an example, the command shows the command
line and PID of the client that triggered the build of a Perl package:
$ sudo guix processes | \
recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
ClientPID: 19419