diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/emacs.texi | 321 | ||||
| -rw-r--r-- | doc/guix.texi | 66 |
2 files changed, 380 insertions, 7 deletions
diff --git a/doc/emacs.texi b/doc/emacs.texi new file mode 100644 index 0000000000..55feb1bf9f --- /dev/null +++ b/doc/emacs.texi @@ -0,0 +1,321 @@ +@node Emacs Interface +@section 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 + +@menu +* Initial Setup: emacs Initial Setup. Preparing @file{~/.emacs}. +* Usage: emacs Usage. Using the interface. +* Configuration: emacs Configuration. Configuring the interface. +@end menu + +@node emacs Initial Setup +@subsection Initial Setup + +To be able to use ``guix.el'', you need to install the following +packages: + +@itemize +@item +@uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or +later; + +@item +@uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is +used for interacting with the Guile process. + +@end itemize + +When it is done, add the following into your init file (@pxref{Init +File,,, emacs, The Emacs Editor}): + +@example +(require 'guix-init nil t) +@end example + +However there is a chance that @code{load-path} of your Emacs does not +contain a directory with ``guix.el'' (usually it is +@file{/usr/share/emacs/site-lisp/}). In that case you need to add it +before requiring (@pxref{Lisp Libraries,,, emacs, The Emacs Editor}): + +@example +(add-to-list 'load-path "/path/to/directory-with-guix.el") +(require 'guix-init) +@end example + +Do not worry about the efficiency of that @code{require} thing. It will +not load the whole ``guix.el'' package, it will just autoload the main +interactive commands (@pxref{Autoload,,, elisp, Emacs Lisp}). + + +@node emacs Usage +@subsection Usage + +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. + +@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. +@end menu + +@node emacs Commands +@subsubsection Commands + +You may use the following commands to display packages and generations: + +@table @kbd +@item M-x guix-all-available-packages +@itemx M-x guix-newest-available-packages +Display all/newest available packages. + +@item M-x guix-installed-packages +Display all packages installed in the current profile. + +@item M-x guix-obsolete-packages +Display obsolete packages (the packages that are installed in the +current profile but cannot be found among available packages). + +@item M-x guix-search-by-name +Display package(s) with the specified name. + +@item M-x guix-search-by-regexp +Search for packages by a specified regexp. By default ``name'', +``synopsis'' and ``description'' of the packages will be searched. This +can be changed by modifying @code{guix-search-params} variable. + +@item M-x guix-generations +List generations for the current profile. With numeric prefix, show so +many last generations. + +@end table + +It is possible to change the currently used profile with +@kbd{M-x@tie{}guix-set-current-profile}. This has the same effect as +specifying @code{--profile} option for @command{guix package} +(@pxref{Invoking guix package}). + +@node emacs General info +@subsubsection General information + +The following keys are available for both ``list'' and ``info'' types of +buffers: + +@table @kbd +@item l +@itemx r +Go backward/forward by the history of the displayed results (this +history is similar to the history of the Emacs @code{help-mode} or +@code{Info-mode}). + +@item g +Revert current buffer: update information about the displayed +packages/generations and redisplay it. + +@item R +Redisplay current buffer (without updating information). + +@item C-c C-z +Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}). + +@item h +@itemx ? +Describe current mode to see all available bindings. + +@end table + +@emph{Hint:} If you need several ``list'' or ``info'' buffers, you can +simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own +history. + +@emph{Warning:} Name/version pairs cannot be used to identify packages +(because a name is not necessarily unique), so ``guix.el'' uses special +identifiers that live only during a guile session, so if the Guix REPL +was restarted, you may want to revert ``list'' buffer (by pressing +@kbd{g}). + +@node emacs List buffer +@subsubsection ``List'' buffer + +An interface of a ``list'' buffer is similar to the interface provided +by ``package.el'' (@pxref{Package Menu,,, emacs, The Emacs Editor}). + +Default key bindings available for both ``package-list'' and +``generation-list'' buffers: + +@table @kbd +@item m +Mark the current entry. +@item M +Mark all entries. +@item u +Unmark the current entry. +@item @key{DEL} +Unmark backward. +@item U +Unmark all entries. +@item S +Sort entries by a specified column. +@end table + +A ``package-list'' buffer additionally provides the following bindings: + +@table @kbd +@item @key{RET} +Describe marked packages (display available information in a +``package-info'' buffer). +@item i +Mark a package for installation (with prefix, prompt for output(s) to +install). +@item d +Mark a package for deletion. +@item ^ +Mark a package for upgrading. +@item x +Execute actions on marked packages. +@end table + +A ``generation-list'' buffer additionally provides the following +bindings: + +@table @kbd +@item @key{RET} +List packages installed in the current generation. +@item i +Describe marked generations (display available information in a +``generation-info'' buffer). +@end table + +@node emacs Info buffer +@subsubsection ``Info'' buffer + +The interface of an ``info'' buffer is similar to the interface of +@code{help-mode} (@pxref{Help Mode,,, emacs, The Emacs Editor}). + +``Info'' buffer contains some buttons (as usual you may use @key{TAB} / +@kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,, +emacs, The Emacs Editor}) which can be used to: + +@itemize @bullet +@item (in a ``package-info'' buffer) + +@itemize @minus +@item install/remove a package; +@item jump to a package location; +@item browse home page of a package; +@item describe packages from ``Inputs'' fields. +@end itemize + +@item (in a ``generation-info'' buffer) + +@itemize @minus +@item remove a generation; +@item list packages installed in a generation; +@item jump to a generation directory. +@end itemize + +@end itemize + + +@node emacs Configuration +@subsection Configuration + +There are many variables you can modify to change the appearance or +behavior of Emacs user interface. Some of these variables are described +in this section. Also you can use Custom Interface (@pxref{Easy +Customization,,, emacs, The Emacs Editor}) to explore/set variables (not +all) and faces. + +@menu +* Guile and Build Options: emacs Build Options. Specifying how packages are built. +* Keymaps: emacs Keymaps. Configuring key bindings. +* Appearance: emacs Appearance. Settings for visual appearance. +@end menu + +@node emacs Build Options +@subsubsection Guile and Build Options + +@table @code +@item guix-guile-program +If you have some special needs for starting a Guile process, you may set +this variable, for example: + +@example +(setq guix-guile-program '("/bin/guile" "--no-auto-compile")) +@end example + +@item guix-use-substitutes +Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking +guix build}). + +@item guix-dry-run +Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix +build}). + +@end table + +@node emacs Keymaps +@subsubsection Keymaps + +If you want to change default key bindings, use the following keymaps +(@pxref{Init Rebinding,,, emacs, The Emacs Editor}): + +@table @code +@item guix-list-mode-map +Parent keymap with general keys for ``list'' buffers. + +@item guix-package-list-mode-map +Keymap with specific keys for ``package-list'' buffers. + +@item guix-generation-list-mode-map +Keymap with specific keys for ``generation-list'' buffers. + +@item guix-info-mode-map +Parent keymap with general keys for ``info'' buffers. + +@item guix-package-info-mode-map +Keymap with specific keys for ``package-info'' buffers. + +@item guix-generation-info-mode-map +Keymap with specific keys for ``generation-info'' buffers. + +@end table + +@node emacs Appearance +@subsubsection Appearance + +You can change almost any aspect of ``list'' / ``info'' buffers using +the following variables: + +@table @code +@item guix-list-column-format +@itemx guix-list-column-titles +@itemx guix-list-column-value-methods +Specify the columns, their names, what and how is displayed in ``list'' +buffers. + +@item guix-info-displayed-params +@itemx guix-info-insert-methods +@itemx guix-info-ignore-empty-vals +@itemx guix-info-param-title-format +@itemx guix-info-multiline-prefix +@itemx guix-info-indent +@itemx guix-info-fill-column +@itemx guix-info-delimiter +Various settings for ``info'' buffers. + +@end table diff --git a/doc/guix.texi b/doc/guix.texi index b6cd57acc2..e0251f5ffd 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -506,14 +506,16 @@ Unless @code{--lose-logs} is used, all the build logs are kept in the @var{localstatedir}. To save space, the daemon automatically compresses them with bzip2 by default. This option disables that. -@item --disable-store-optimization +@item --disable-deduplication +@cindex deduplication Disable automatic file ``deduplication'' in the store. By default, files added to the store are automatically ``deduplicated'': -if a newly added file is identical as another one found in the store, -the daemon makes the new file a hard link to the other file. This -slightly increases the input/output load at the end of a build process. -This option disables this. +if a newly added file is identical to another one found in the store, +the daemon makes the new file a hard link to the other file. This can +noticeably reduce disk usage, at the expense of slightly increasde +input/output load at the end of a build process. This option disables +this optimization. @item --gc-keep-outputs[=yes|no] Tell whether the garbage collector (GC) must keep outputs of live @@ -579,6 +581,7 @@ management tools it provides. @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. @@ -953,6 +956,8 @@ 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 @@ -1457,7 +1462,10 @@ definitions like the one above may be automatically converted from the Nixpkgs distribution using the @command{guix import} command.}, the package may actually be built using the @code{guix build} command-line tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for -more information on how to test package definitions. +more information on how to test package definitions, and +@ref{Invoking guix lint}, for information on how to check a definition +for style conformance. + Eventually, updating the package definition to a new upstream version can be partly automated by the @command{guix refresh} command @@ -2270,6 +2278,22 @@ search path to be copied in the store, compiled, and made available in the load path during the execution of @var{exp}---e.g., @code{((guix build utils) (guix build gnu-build-system))}. +When @var{references-graphs} is true, it must be a list of tuples of one of the +following forms: + +@example +(@var{file-name} @var{package}) +(@var{file-name} @var{package} @var{output}) +(@var{file-name} @var{derivation}) +(@var{file-name} @var{derivation} @var{output}) +(@var{file-name} @var{store-item}) +@end example + +The right-hand-side of each element of @var{references-graphs} is automatically made +an input of the build process of @var{exp}. In the build environment, each +@var{file-name} contains the reference graph of the corresponding item, in a simple +text format. + The other arguments are as for @code{derivation} (@pxref{Derivations}). @end deffn @@ -2326,6 +2350,7 @@ programming interface of Guix in a convenient way. * Invoking guix download:: Downloading a file and printing its hash. * Invoking guix hash:: Computing the cryptographic hash of a file. * Invoking guix refresh:: Updating package definitions. +* Invoking guix lint:: Finding errors in package definitions. @end menu @node Invoking guix build @@ -2703,6 +2728,29 @@ for in @code{$PATH}. @end table +@node Invoking guix lint +@section Invoking @command{guix lint} +The @command{guix lint} is meant to help package developers avoid common +errors and use a consistent style. It runs a few checks on a given set of +packages in order to find common mistakes in their definitions. + +The general syntax is: + +@example +guix lint @var{options} @var{package}@dots{} +@end example + +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. + +@end table @c ********************************************************************* @node GNU Distribution @@ -2946,7 +2994,7 @@ more information, @pxref{Invoking guix system}. This command may trigger downloads or builds of missing packages, which can take some time. Once that command has completed---and hopefully succeeded!---you can -unmount @file{/mnt} and boot into the new system. Cross fingers, and +run @command{reboot} and boot into the new system. Cross fingers, and join us on @code{#guix} on the Freenode IRC network or on @file{guix-devel@@gnu.org} to share your experience---good or not so good. @@ -3533,6 +3581,10 @@ system declaration like this: #:extra-modules '("my.ko" "modules.ko"))) @end example +@noindent +Note that for the example above, the SRFI-26 module needs to be imported +(@pxref{SRFI-26,,, guile, GNU Guile Reference Manual}). + It also handles common use cases that involves using the system as a QEMU guest, or as a ``live'' system whose root file system is volatile. |