diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guix.texi | 170 |
1 files changed, 123 insertions, 47 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 2f9fcbe3bf..f8e7436cf1 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1795,25 +1795,14 @@ available. @node Limitations @section Limitations -As of version @value{VERSION}, Guix System is -not production-ready. It may contain bugs and lack important -features. Thus, if you are looking for a stable production system that -respects your freedom as a computer user, a good solution at this point -is to consider @url{http://www.gnu.org/distros/free-distros.html, one of -the more established GNU/Linux distributions}. We hope you can soon switch -to the Guix System without fear, of course. In the meantime, you can -also keep using your distribution and try out the package manager on top -of it (@pxref{Installation}). - -Before you proceed with the installation, be aware of the following -noteworthy limitations applicable to version @value{VERSION}: +We consider Guix System to be ready for a wide range of ``desktop'' and server +use cases. The reliability guarantees it provides---transactional upgrades +and rollbacks, reproducibility---make it a solid foundation. -@itemize -@item -The installation process does not include a graphical user interface and -requires familiarity with GNU/Linux (see the following subsections to -get a feel of what that means.) +Nevertheless, before you proceed with the installation, be aware of the +following noteworthy limitations applicable to version @value{VERSION}: +@itemize @item Support for the Logical Volume Manager (LVM) is missing. @@ -1822,18 +1811,14 @@ More and more system services are provided (@pxref{Services}), but some may be missing. @item -More than 8,500 packages are available, but you might -occasionally find that a useful package is missing. - -@item GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), -as well as a number of X11 window managers. However, some graphical -applications may be missing, as well as KDE. +as well as a number of X11 window managers. However, KDE is currently +missing. @end itemize -You have been warned! But more than a disclaimer, this is an invitation -to report issues (and success stories!), and to join us in improving it. -@xref{Contributing}, for more info. +More than a disclaimer, this is an invitation to report issues (and success +stories!), and to join us in improving it. @xref{Contributing}, for more +info. @node Hardware Considerations @@ -1856,7 +1841,7 @@ devices. WiFi devices known to work include those using Atheros chips driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core Revision 5), which corresponds to the @code{b43-open} Linux-libre driver. Free firmware exists for both and is available -out-of-the-box on Guix System, as part of @var{%base-firmware} +out-of-the-box on Guix System, as part of @code{%base-firmware} (@pxref{operating-system Reference, @code{firmware}}). @cindex RYF, Respects Your Freedom @@ -3385,7 +3370,7 @@ deleted. The set of garbage collector roots (``GC roots'' for short) includes default user profiles; by default, the symlinks under @file{/var/guix/gcroots} represent these GC roots. New GC roots can be added with @command{guix build --root}, for example (@pxref{Invoking -guix build}). +guix build}). The @command{guix gc --list-roots} command lists them. Prior to running @code{guix gc --collect-garbage} to make space, it is often useful to remove old generations from user profiles; that way, old @@ -3438,8 +3423,22 @@ as @code{500MiB}, as described above. When @var{free} or more is already available in @file{/gnu/store}, do nothing and exit immediately. +@item --delete-generations[=@var{duration}] +@itemx -d [@var{duration}] +Before starting the garbage collection process, delete all the generations +older than @var{duration}, for all the user profiles; when run as root, this +applies to all the profiles @emph{of all the users}. + +For example, this command deletes all the generations of all your profiles +that are older than 2 months (except generations that are current), and then +proceeds to free space until at least 10 GiB are available: + +@example +guix gc -d 2m -F 10G +@end example + @item --delete -@itemx -d +@itemx -D Attempt to delete all the store files and directories specified as arguments. This fails if some of the files are not in the store, or if they are still live. @@ -3451,6 +3450,10 @@ This prints nothing unless the daemon was started with @option{--cache-failures} (@pxref{Invoking guix-daemon, @option{--cache-failures}}). +@item --list-roots +List the GC roots owned by the user; when run as root, list @emph{all} the GC +roots. + @item --clear-failures Remove the specified store items from the failed-build cache. @@ -5406,6 +5409,27 @@ automatically corrected. @end table @end deftp +@deffn {Scheme Syntax} this-package +When used in the @emph{lexical scope} of a package field definition, this +identifier resolves to the package being defined. + +The example below shows how to add a package as a native input of itself when +cross-compiling: + +@example +(package + (name "guile") + ;; ... + + ;; When cross-compiled, Guile, for example, depends on + ;; a native version of itself. Add it here. + (native-inputs (if (%current-target-system) + `(("self" ,this-package)) + '()))) +@end example + +It is an error to refer to @code{this-package} outside a package definition. +@end deffn @node origin Reference @subsection @code{origin} Reference @@ -6192,6 +6216,33 @@ is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}. @end table @end defvr +@defvr {Scheme Variable} linux-module-build-system +@var{linux-module-build-system} allows building Linux kernel modules. + +@cindex build phases +This build system is an extension of @var{gnu-build-system}, but with the +following phases changed: + +@table @code + +@item configure +This phase configures the environment so that the Linux kernel's Makefile +can be used to build the external kernel module. + +@item build +This phase uses the Linux kernel's Makefile in order to build the external +kernel module. + +@item install +This phase uses the Linux kernel's Makefile in order to install the external +kernel module. +@end table + +It is possible and useful to specify the Linux kernel to use for building +the module (in the "arguments" form of a package using the +linux-module-build-system, use the key #:linux to specify it). +@end defvr + Lastly, for packages that do not need anything as sophisticated, a ``trivial'' build system is provided. It is trivial in the sense that it provides basically no support: it does not pull any implicit inputs, @@ -10406,6 +10457,10 @@ the command-line of the kernel---e.g., @code{("console=ttyS0")}. @item @code{bootloader} The system bootloader configuration object. @xref{Bootloader Configuration}. +@item @code{label} +This is the label (a string) as it appears in the bootloader's menu entry. +The default label includes the kernel name and version. + @item @code{keyboard-layout} (default: @code{#f}) This field specifies the keyboard layout to use in the console. It can be either @code{#f}, in which case the default keyboard layout is used (usually @@ -10558,6 +10613,27 @@ is that only @code{root} and members of the @code{wheel} group may use @code{sudo}. @end table + +@deffn {Scheme Syntax} this-operating-system +When used in the @emph{lexical scope} of an operating system field definition, +this identifier resolves to the operating system being defined. + +The example below shows how to refer to the operating system being defined in +the definition of the @code{label} field: + +@example +(use-modules (gnu) (guix)) + +(operating-system + ;; ... + (label (package-full-name + (operating-system-kernel this-operating-system)))) +@end example + +It is an error to refer to @code{this-operating-system} outside an operating +system definition. +@end deffn + @end deftp @node File Systems @@ -23122,7 +23198,7 @@ The port to bind the server to. @cindex fingerprint @subsubheading Fingerprint Service -The @code{(gnu services fingerprint)} module provides a DBus service to +The @code{(gnu services authentication)} module provides a DBus service to read and identify fingerprints via a fingerprint sensor. @defvr {Scheme Variable} fprintd-service-type @@ -23983,7 +24059,7 @@ must @emph{not} be an OS device name such as @file{/dev/sda1}. @end deftp @c FIXME: Write documentation once it's stable. -Fow now only GRUB has theme support. GRUB themes are created using +For now only GRUB has theme support. GRUB themes are created using the @code{grub-theme} form, which is not documented yet. @defvr {Scheme Variable} %default-theme @@ -24669,23 +24745,23 @@ exception is the @dfn{boot service type}, which is the ultimate service. Optionally, a default value for instances of this type. @end enumerate -In this example, @var{guix-service-type} extends three services: +In this example, @code{guix-service-type} extends three services: -@table @var +@table @code @item shepherd-root-service-type -The @var{guix-shepherd-service} procedure defines how the Shepherd +The @code{guix-shepherd-service} procedure defines how the Shepherd service is extended. Namely, it returns a @code{<shepherd-service>} object that defines how @command{guix-daemon} is started and stopped (@pxref{Shepherd Services}). @item account-service-type -This extension for this service is computed by @var{guix-accounts}, +This extension for this service is computed by @code{guix-accounts}, which returns a list of @code{user-group} and @code{user-account} objects representing the build user accounts (@pxref{Invoking guix-daemon}). @item activation-service-type -Here @var{guix-activation} is a procedure that returns a gexp, which is +Here @code{guix-activation} is a procedure that returns a gexp, which is a code snippet to run at ``activation time''---e.g., when the service is booted. @end table @@ -24710,7 +24786,7 @@ value is omitted, the default value specified by (service guix-service-type) @end example -@var{guix-service-type} is quite simple because it extends other +@code{guix-service-type} is quite simple because it extends other services but is not extensible itself. @c @subsubsubsection Extensible Service Types @@ -24736,7 +24812,7 @@ The service type for an @emph{extensible} service looks like this: This is the service type for the @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device management daemon}. Compared to the previous example, in addition to an -extension of @var{shepherd-root-service-type}, we see two new fields: +extension of @code{shepherd-root-service-type}, we see two new fields: @table @code @item compose @@ -24763,7 +24839,7 @@ them (@pxref{Invoking guix system}). @end table There can be only one instance of an extensible service type such as -@var{udev-service-type}. If there were more, the +@code{udev-service-type}. If there were more, the @code{service-extension} specifications would be ambiguous. Still here? The next section provides a reference of the programming @@ -24837,7 +24913,7 @@ Here is an example of how a service is created and manipulated: The @code{modify-services} form provides a handy way to change the parameters of some of the services of a list such as -@var{%base-services} (@pxref{Base Services, @code{%base-services}}). It +@code{%base-services} (@pxref{Base Services, @code{%base-services}}). It evaluates to a list of services. Of course, you could always use standard list combinators such as @code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual}); @@ -25018,8 +25094,8 @@ You can actually generate such a graph for any operating system definition using the @command{guix system shepherd-graph} command (@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). -The @var{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @var{shepherd-root-service-type}; it can be extended +The @code{%shepherd-root-service} is a service object representing +PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by passing it lists of @code{<shepherd-service>} objects. @deftp {Data Type} shepherd-service @@ -25067,10 +25143,10 @@ A documentation string, as shown when running: herd doc @var{service-name} @end example -where @var{service-name} is one of the symbols in @var{provision} +where @var{service-name} is one of the symbols in @code{provision} (@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). -@item @code{modules} (default: @var{%default-modules}) +@item @code{modules} (default: @code{%default-modules}) This is the list of modules that must be in scope when @code{start} and @code{stop} are evaluated. @@ -25317,7 +25393,7 @@ order of magnitudes lower than a full rebuild of the dependency chain. @cindex replacements of packages, for grafts For instance, suppose a security update needs to be applied to Bash. Guix developers will provide a package definition for the ``fixed'' -Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining +Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining Packages}). Then, the original package definition is augmented with a @code{replacement} field pointing to the package containing the bug fix: @@ -25332,14 +25408,14 @@ Packages}). Then, the original package definition is augmented with a From there on, any package depending directly or indirectly on Bash---as reported by @command{guix gc --requisites} (@pxref{Invoking guix gc})---that is installed is automatically ``rewritten'' to refer to -@var{bash-fixed} instead of @var{bash}. This grafting process takes +@code{bash-fixed} instead of @code{bash}. This grafting process takes time proportional to the size of the package, usually less than a minute for an ``average'' package on a recent machine. Grafting is recursive: when an indirect dependency requires grafting, then grafting ``propagates'' up to the package that the user is installing. Currently, the length of the name and version of the graft and that of -the package it replaces (@var{bash-fixed} and @var{bash} in the example +the package it replaces (@code{bash-fixed} and @code{bash} in the example above) must be equal. This restriction mostly comes from the fact that grafting works by patching files, including binary files, directly. Other restrictions may apply: for instance, when adding a graft to a |