diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/emacs.texi | 102 | ||||
| -rw-r--r-- | doc/guix.texi | 166 |
2 files changed, 229 insertions, 39 deletions
diff --git a/doc/emacs.texi b/doc/emacs.texi index 180037a88f..db2e657d27 100644 --- a/doc/emacs.texi +++ b/doc/emacs.texi @@ -1,29 +1,22 @@ @node Emacs Interface -@section Emacs Interface +@chapter Emacs Interface @cindex Emacs -GNU Guix comes with a visual user interface for GNU@tie{}Emacs, known -as ``guix.el''. It can be used for routine package management tasks, -pretty much like the @command{guix package} command (@pxref{Invoking -guix package}). Specifically, ``guix.el'' makes it easy to: - -@itemize -@item browse and display packages and generations; -@item search, install, upgrade and remove packages; -@item display packages from previous generations; -@item do some other useful things. -@end itemize +GNU Guix comes with several useful modules (known as ``guix.el'') for +GNU@tie{}Emacs which are intended to make an Emacs user interaction with +Guix convenient and fun. @menu * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. -* Usage: Emacs Usage. Using the interface. -* Configuration: Emacs Configuration. Configuring the interface. +* Package Management: Emacs Package Management. Managing packages and generations. +* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. * Completions: Emacs Completions. Completing @command{guix} shell command. @end menu + @node Emacs Initial Setup -@subsection Initial Setup +@section Initial Setup On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el'' is ready to use, provided Guix is installed system-wide, which is the @@ -43,6 +36,12 @@ later; @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is used for interacting with the Guile process. +@item +@uref{https://github.com/magit/magit/, magit-popup library}. You +already have this library if you use Magit 2.1.0 or later. This library +is an optional dependency---it is required only for @kbd{M-x@tie{}guix} +command (@pxref{Emacs Popup Interface}). + @end itemize When it is done ``guix.el'' may be configured by requiring a special @@ -105,22 +104,32 @@ emacs, The GNU Emacs Manual}). You can activate Emacs packages installed in your profile whenever you want using @kbd{M-x@tie{}guix-emacs-load-autoloads}. -@node Emacs Usage -@subsection Usage + +@node Emacs Package Management +@section Package Management Once ``guix.el'' has been successfully configured, you should be able to -use commands for displaying packages and generations. This information -can be displayed in a ``list'' or ``info'' buffer. +use a visual interface for routine package management tasks, pretty much +like the @command{guix package} command (@pxref{Invoking guix package}). +Specifically, it makes it easy to: + +@itemize +@item browse and display packages and generations; +@item search, install, upgrade and remove packages; +@item display packages from previous generations; +@item do some other useful things. +@end itemize @menu * Commands: Emacs Commands. @kbd{M-x guix-@dots{}} * General information: Emacs General info. Common for both interfaces. * ``List'' buffer: Emacs List buffer. List-like interface. * ``Info'' buffer: Emacs Info buffer. Help-like interface. +* Configuration: Emacs Configuration. Configuring the interface. @end menu @node Emacs Commands -@subsubsection Commands +@subsection Commands All commands for displaying packages and generations use the current profile, which can be changed with @@ -191,7 +200,7 @@ Once @command{guix pull} has succeeded, the Guix REPL is restared. This allows you to keep using the Emacs interface with the updated Guix. @node Emacs General info -@subsubsection General information +@subsection General information The following keys are available for both ``list'' and ``info'' types of buffers: @@ -235,7 +244,7 @@ was restarted, you may want to revert ``list'' buffer (by pressing @kbd{g}). @node Emacs List buffer -@subsubsection ``List'' buffer +@subsection ``List'' buffer An interface of a ``list'' buffer is similar to the interface provided by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}). @@ -310,7 +319,7 @@ with another marked generation. @end table @node Emacs Info buffer -@subsubsection ``Info'' buffer +@subsection ``Info'' buffer The interface of an ``info'' buffer is similar to the interface of @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}). @@ -484,12 +493,49 @@ Various settings for ``info'' buffers. @end table +@node Emacs Popup Interface +@section Popup Interface + +If you ever used Magit, you know what ``popup interface'' is +(@pxref{Top,,, magit-popup, Magit-Popup User Manual}). Even if you are +not acquainted with Magit, there should be no worries as it is very +intuitive. + +So @kbd{M-x@tie{}guix} command provides a top-level popup interface for +all available guix commands. When you select an option, you'll be +prompted for a value in the minibuffer. Many values have completions, +so don't hesitate to press @key{TAB} key. Multiple values (for example, +packages or lint checkers) should be separated by commas. + +After specifying all options and switches for a command, you may choose +one of the available actions. The following default actions are +available for all commands: + +@itemize + +@item +Run the command in the Guix REPL. It is faster than running +@code{guix@tie{}@dots{}} command directly in shell, as there is no +need to run another guile process and to load required modules there. + +@item +Run the command in a shell buffer. You can set +@code{guix-run-in-shell-function} variable to fine tune the shell buffer +you want to use. + +@item +Add the command line to the kill ring (@pxref{Kill Ring,,, emacs, The +GNU Emacs Manual}). + +@end itemize + + @node Emacs Prettify -@subsection Guix Prettify Mode +@section Guix Prettify Mode -Along with ``guix.el'', GNU@tie{}Guix comes with ``guix-prettify.el''. -It provides a minor mode for abbreviating store file names by replacing -hash sequences of symbols with ``@dots{}'': +GNU@tie{}Guix also comes with ``guix-prettify.el''. It provides a minor +mode for abbreviating store file names by replacing hash sequences of +symbols with ``@dots{}'': @example /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1 @@ -526,7 +572,7 @@ mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example: @node Emacs Completions -@subsection Shell Completions +@section Shell Completions Another feature that becomes available after configuring Emacs interface (@pxref{Emacs Initial Setup}) is completing of @command{guix} diff --git a/doc/guix.texi b/doc/guix.texi index f69440c325..9ae91a8d1e 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -70,6 +70,7 @@ package management tool written for the GNU system. * Introduction:: What is Guix about? * Installation:: Installing Guix. * Package Management:: Package installation, upgrade, etc. +* Emacs Interface:: Using Guix from Emacs. * Programming Interface:: Using Guix in Scheme. * Utilities:: Package management commands. * GNU Distribution:: Software for your friendly GNU system. @@ -101,13 +102,20 @@ Package Management * Features:: How Guix will make your life brighter. * Invoking guix package:: Package installation, removal, etc. -* Emacs Interface:: Package management from Emacs. * Substitutes:: Downloading pre-built binaries. * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. * Invoking guix archive:: Exporting and importing store files. +Emacs Interface + +* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. +* Package Management: Emacs Package Management. Managing packages and generations. +* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. +* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. +* Completions: Emacs Completions. Completing @command{guix} shell command. + Programming Interface * Defining Packages:: Defining new packages. @@ -964,14 +972,13 @@ features. This chapter describes the main features of Guix, as well as the package management tools it provides. Two user interfaces are provided for -routine package management tasks: a command-line interface -(@pxref{Invoking guix package, @code{guix package}}), and a visual user -interface in Emacs (@pxref{Emacs Interface}). +routine package management tasks: A command-line interface described below +(@pxref{Invoking guix package, @code{guix package}}), as well as a visual user +interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}). @menu * Features:: How Guix will make your life brighter. * Invoking guix package:: Package installation, removal, etc. -* Emacs Interface:: Package management from Emacs. * Substitutes:: Downloading pre-built binaries. * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. @@ -1455,8 +1462,6 @@ Finally, since @command{guix package} may actually start build processes, it supports all the common build options that @command{guix build} supports (@pxref{Invoking guix build, common build options}). -@include emacs.texi - @node Substitutes @section Substitutes @@ -1898,6 +1903,8 @@ automatically builds them. The build process may be controlled with the same options that can be passed to the @command{guix build} command (@pxref{Invoking guix build, common build options}). +@c ********************************************************************* +@include emacs.texi @c ********************************************************************* @node Programming Interface @@ -2484,6 +2491,16 @@ passes flags specified by the @code{#:make-maker-flags} or Which Perl package is used can be specified with @code{#:perl}. @end defvr +@defvr {Scheme Variable} r-build-system +This variable is exported by @code{(guix build-system r)}. It +implements the build procedure used by @uref{http://r-project.org, R} +packages, which essentially is little more than running @code{R CMD +INSTALL --library=/gnu/store/@dots{}} in an environment where +@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests +are run after installation using the R function +@code{tools::testInstalledPackage}. +@end defvr + @defvr {Scheme Variable} ruby-build-system This variable is exported by @code{(guix build-system ruby)}. It implements the RubyGems build procedure used by Ruby packages, which @@ -3612,7 +3629,7 @@ Make @var{file} a symlink to the result, and register it as a garbage collector root. @item --log-file -Return the build log file names for the given +Return the build log file names or URLs for the given @var{package-or-derivation}s, or raise an error if build logs are missing. @@ -3626,7 +3643,19 @@ guix build --log-file guile guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)' @end example +If a log is unavailable locally, and unless @code{--no-substitutes} is +passed, the command looks for a corresponding log on one of the +substitute servers (as specified with @code{--substitute-urls}.) + +So for instance, let's say you want to see the build log of GDB on MIPS +but you're actually on an @code{x86_64} machine: +@example +$ guix build --log-file gdb -s mips64el-linux +http://hydra.gnu.org/log/@dots{}-gdb-7.10 +@end example + +You can freely access a huge library of build logs! @end table @cindex common build options @@ -3932,6 +3961,21 @@ Perl module: guix import cpan Acme::Boolean @end example +@item cran +@cindex CRAN +Import meta-data from @uref{http://cran.r-project.org/, CRAN}, the +central repository for the @uref{http://r-project.org, GNU@tie{}R +statistical and graphical environment}. + +Information is extracted from the HTML package description. + +The command command below imports meta-data for the @code{Cairo} +R package: + +@example +guix import cran Cairo +@end example + @item nix Import meta-data from a local copy of the source of the @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This @@ -4385,6 +4429,16 @@ the values listed above. @item --list-types List the supported graph types. + +@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 @end table @@ -5477,7 +5531,7 @@ special-case and is automatically added whether or not it is specified. A @dfn{locale} defines cultural conventions for a particular language and region of the world (@pxref{Locales,,, libc, The GNU C Library Reference Manual}). Each locale has a name that typically has the form -@code{@var{language}_@var{territory}.@var{charset}}---e.g., +@code{@var{language}_@var{territory}.@var{codeset}}---e.g., @code{fr_LU.utf8} designates the locale for the French language, with cultural conventions from Luxembourg, and using the UTF-8 encoding. @@ -5538,9 +5592,17 @@ IANA}. @end deftp @defvr {Scheme Variable} %default-locale-definitions -An arbitrary list of commonly used locales, used as the default value of -the @code{locale-definitions} field of @code{operating-system} +An arbitrary list of commonly used UTF-8 locales, used as the default +value of the @code{locale-definitions} field of @code{operating-system} declarations. + +@cindex locale name +@cindex normalized codeset in locale names +These locale definitions use the @dfn{normalized codeset} for the part +that follows the dot in the name (@pxref{Using gettextized software, +normalized codeset,, libc, The GNU C Library Reference Manual}). So for +instance it has @code{uk_UA.utf8} but @emph{not}, say, +@code{uk_UA.UTF-8}. @end defvr @node Services @@ -6009,6 +6071,7 @@ adds or adjust services for a typical ``desktop'' setup. In particular, it adds a graphical login manager (@pxref{X Window, @code{slim-service}}), a network management tool (@pxref{Networking Services, @code{wicd-service}}), energy and color management services, +the @code{elogind} login and seat manager, the Polkit privilege service, the GeoClue location service, an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the name service switch service configured to be able to use @code{nss-mdns} (@pxref{Name Service @@ -6037,6 +6100,87 @@ and policy files. For example, to allow avahi-daemon to use the system bus, @var{services} must be equal to @code{(list avahi)}. @end deffn +@deffn {Monadic Procedure} elogind-service @ + [#:elogind @var{elogind}] [#:config @var{config}] +Return a service that runs the @code{elogind} login and +seat management daemon. @uref{https://github.com/andywingo/elogind, +Elogind} exposes a D-Bus interface that can be used to know which users +are logged in, know what kind of sessions they have open, suspend the +system, inhibit system suspend, reboot the system, and other tasks. + +Elogind handles most system-level power events for a computer, for +example suspending the system when a lid is closed, or shutting it down +when the power button is pressed. + +The @var{config} keyword argument specifies the configuration for +elogind, and should be the result of a @code{(elogind-configuration +(@var{parameter} @var{value})...)} invocation. Available parameters and +their default values are: + +@table @code +@item kill-user-processes? +@code{#f} +@item kill-only-users +@code{()} +@item kill-exclude-users +@code{("root")} +@item inhibit-delay-max-seconds +@code{5} +@item handle-power-key +@code{poweroff} +@item handle-suspend-key +@code{suspend} +@item handle-hibernate-key +@code{hibernate} +@item handle-lid-switch +@code{suspend} +@item handle-lid-switch-docked +@code{ignore} +@item power-key-ignore-inhibited? +@code{#f} +@item suspend-key-ignore-inhibited? +@code{#f} +@item hibernate-key-ignore-inhibited? +@code{#f} +@item lid-switch-ignore-inhibited? +@code{#t} +@item holdoff-timeout-seconds +@code{30} +@item idle-action +@code{ignore} +@item idle-action-seconds +@code{(* 30 60)} +@item runtime-directory-size-percent +@code{10} +@item runtime-directory-size +@code{#f} +@item remove-ipc? +@code{#t} +@item suspend-state +@code{("mem" "standby" "freeze")} +@item suspend-mode +@code{()} +@item hibernate-state +@code{("disk")} +@item hibernate-mode +@code{("platform" "shutdown")} +@item hybrid-sleep-state +@code{("disk")} +@item hybrid-sleep-mode +@code{("suspend" "platform" "shutdown")} +@end table +@end deffn + +@deffn {Monadic Procedure} polkit-service @ + [#:polkit @var{polkit}] +Return a service that runs the Polkit privilege manager. +@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit} allows +system administrators to grant access to privileged operations in a +structured way. For example, polkit rules can allow a logged-in user +whose session is active to shut down the machine, if there are no other +users active. +@end deffn + @deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @ [#:watts-up-pro? #f] @ [#:poll-batteries? #t] @ |