diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 124 |
1 files changed, 107 insertions, 17 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 4095bdb51b..a12210db8a 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -2834,6 +2834,15 @@ guix pack -S /opt/gnu/bin=bin guile emacs geiser @noindent That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy. +@cindex relocatable binaries, with @command{guix pack} +What if the recipient of your pack does not have root privileges on +their machine, and thus cannot unpack it in the root file system? In +that case, you will want to use the @code{--relocatable} option (see +below). This option produces @dfn{relocatable binaries}, meaning they +they can be placed anywhere in the file system hierarchy: in the example +above, users can unpack your tarball in their home directory and +directly run @file{./opt/gnu/bin/guile}. + Alternatively, you can produce a pack in the Docker image format using the following command: @@ -2867,6 +2876,39 @@ This produces a tarball that follows the Docker Image Specification}. @end table +@item --relocatable +@itemx -R +Produce @dfn{relocatable binaries}---i.e., binaries that can be placed +anywhere in the file system hierarchy and run from there. For example, +if you create a pack containing Bash with: + +@example +guix pack -R -S /mybin=bin bash +@end example + +@noindent +... you can copy that pack to a machine that lacks Guix, and from your +home directory as a normal user, run: + +@example +tar xf pack.tar.gz +./mybin/sh +@end example + +@noindent +In that shell, if you type @code{ls /gnu/store}, you'll notice that +@file{/gnu/store} shows up and contains all the dependencies of +@code{bash}, even though the machine actually lacks @file{/gnu/store} +altogether! That is probably the simplest way to deploy Guix-built +software on a non-Guix machine. + +There's a gotcha though: this technique relies on the @dfn{user +namespace} feature of the kernel Linux, which allows unprivileged users +to mount or change root. Old versions of Linux did not support it, and +some GNU/Linux distributions turn it off; on these systems, programs +from the pack @emph{will fail to run}, unless they are unpacked in the +root file system. + @item --expression=@var{expr} @itemx -e @var{expr} Consider the package @var{expr} evaluates to. @@ -3750,6 +3792,25 @@ that should be run during the @code{build} phase. By default the @end defvr +@defvr {Scheme Variable} android-ndk-build-system +@cindex Android distribution +@cindex Android NDK build system +This variable is exported by @code{(guix build-system android-ndk)}. It +implements a build procedure for Android NDK (native development kit) +packages using a Guix-specific build process. + +The build system assumes that packages install their public interface +(header) files to the subdirectory "include" of the "out" output and +their libraries to the subdirectory "lib" of the "out" output. + +It's also assumed that the union of all the dependencies of a package +has no conflicting files. + +For the time being, cross-compilation is not supported - so right now +the libraries and header files are assumed to be host tools. + +@end defvr + @defvr {Scheme Variable} asdf-build-system/source @defvrx {Scheme Variable} asdf-build-system/sbcl @defvrx {Scheme Variable} asdf-build-system/ecl @@ -6774,15 +6835,33 @@ where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g., Package developers can specify in package recipes the @uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)} -name and version of the package when they differ from the name that Guix -uses, as in this example: +name and version of the package when they differ from the name or version +that Guix uses, as in this example: @example (package (name "grub") ;; @dots{} ;; CPE calls this package "grub2". - (properties '((cpe-name . "grub2")))) + (properties '((cpe-name . "grub2") + (cpe-version . "2.3"))) +@end example + +@c See <http://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: + +@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"))))) @end example @item formatting @@ -6826,19 +6905,23 @@ 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 a package specification such as @code{gcc@@4.8} +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: @example $ guix size coreutils store item total self -/gnu/store/@dots{}-coreutils-8.23 70.0 13.9 19.8% -/gnu/store/@dots{}-gmp-6.0.0a 55.3 2.5 3.6% -/gnu/store/@dots{}-acl-2.2.52 53.7 0.5 0.7% -/gnu/store/@dots{}-attr-2.4.46 53.2 0.3 0.5% -/gnu/store/@dots{}-gcc-4.8.4-lib 52.9 15.7 22.4% -/gnu/store/@dots{}-glibc-2.21 37.2 37.2 53.1% +/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 @end example @cindex closure @@ -6858,17 +6941,21 @@ 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 -70@tie{}MiB, half of which is taken by libc. (That libc represents a -large fraction of the closure is not a problem @i{per se} because it is -always available on the system anyway.) - -When the package passed to @command{guix size} is available in the -store, @command{guix size} queries the daemon to determine its +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.) + +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 package is @emph{not} in the store, @command{guix size} +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. @@ -14924,6 +15011,9 @@ networking interface. @item @code{package} (default: @code{bitlbee}) The BitlBee package to use. +@item @code{plugins} (default: @code{'()}) +List of plugin packages to use---e.g., @code{bitlbee-discord}. + @item @code{extra-settings} (default: @code{""}) Configuration snippet added as-is to the BitlBee configuration file. @end table |