doc/emacs.texi

   1 @node Emacs Interface
   2 @section Emacs Interface
   3
   4 @cindex emacs
   5 GNU Guix comes with a visual user interface for GNU@tie{}Emacs, known
   6 as ``guix.el''.  It can be used for routine package management tasks,
   7 pretty much like the @command{guix package} command (@pxref{Invoking
   8 guix package}).  Specifically, ``guix.el'' makes it easy to:
   9
  10 @itemize
  11 @item browse and display packages and generations;
  12 @item search, install, upgrade and remove packages;
  13 @item display packages from previous generations;
  14 @item do some other useful things.
  15 @end itemize
  16
  17 @menu
  18 * Initial Setup: emacs Initial Setup.   Preparing @file{~/.emacs}.
  19 * Usage: emacs Usage.                   Using the interface.
  20 * Configuration: emacs Configuration.   Configuring the interface.
  21 @end menu
  22
  23 @node emacs Initial Setup
  24 @subsection Initial Setup
  25
  26 To be able to use ``guix.el'', you need to install the following
  27 packages:
  28
  29 @itemize
  30 @item
  31 @uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or
  32 later;
  33
  34 @item
  35 @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is
  36 used for interacting with the Guile process.
  37
  38 @end itemize
  39
  40 When it is done, add the following into your init file (@pxref{Init
  41 File,,, emacs, The Emacs Editor}):
  42
  43 @example
  44 (require 'guix-init nil t)
  45 @end example
  46
  47 However there is a chance that @code{load-path} of your Emacs does not
  48 contain a directory with ``guix.el'' (usually it is
  49 @file{/usr/share/emacs/site-lisp/}).  In that case you need to add it
  50 before requiring (@pxref{Lisp Libraries,,, emacs, The Emacs Editor}):
  51
  52 @example
  53 (add-to-list 'load-path "/path/to/directory-with-guix.el")
  54 (require 'guix-init)
  55 @end example
  56
  57 Do not worry about the efficiency of that @code{require} thing.  It will
  58 not load the whole ``guix.el'' package, it will just autoload the main
  59 interactive commands (@pxref{Autoload,,, elisp, Emacs Lisp}).
  60
  61
  62 @node emacs Usage
  63 @subsection Usage
  64
  65 Once ``guix.el'' has been successfully configured, you should be able to
  66 use commands for displaying packages and generations.  This information
  67 can be displayed in a ``list'' or ``info'' buffer.
  68
  69 @menu
  70 * Commands: emacs Commands.                     @kbd{M-x guix-@dots{}}
  71 * General information: emacs General info.      Common for both interfaces.
  72 * ``List'' buffer: emacs List buffer.           List-like interface.
  73 * ``Info'' buffer: emacs Info buffer.           Help-like interface.
  74 @end menu
  75
  76 @node emacs Commands
  77 @subsubsection Commands
  78
  79 You may use the following commands to display packages and generations:
  80
  81 @table @kbd
  82 @item M-x guix-all-available-packages
  83 @itemx M-x guix-newest-available-packages
  84 Display all/newest available packages.
  85
  86 @item M-x guix-installed-packages
  87 Display all packages installed in the current profile.
  88
  89 @item M-x guix-obsolete-packages
  90 Display obsolete packages (the packages that are installed in the
  91 current profile but cannot be found among available packages).
  92
  93 @item M-x guix-search-by-name
  94 Display package(s) with the specified name.
  95
  96 @item M-x guix-search-by-regexp
  97 Search for packages by a specified regexp.  By default ``name'',
  98 ``synopsis'' and ``description'' of the packages will be searched.  This
  99 can be changed by modifying @code{guix-search-params} variable.
 100
 101 @item M-x guix-generations
 102 List generations for the current profile.  With numeric prefix, show so
 103 many last generations.
 104
 105 @end table
 106
 107 It is possible to change the currently used profile with
 108 @kbd{M-x@tie{}guix-set-current-profile}.  This has the same effect as
 109 specifying @code{--profile} option for @command{guix package}
 110 (@pxref{Invoking guix package}).
 111
 112 @node emacs General info
 113 @subsubsection General information
 114
 115 The following keys are available for both ``list'' and ``info'' types of
 116 buffers:
 117
 118 @table @kbd
 119 @item l
 120 @itemx r
 121 Go backward/forward by the history of the displayed results (this
 122 history is similar to the history of the Emacs @code{help-mode} or
 123 @code{Info-mode}).
 124
 125 @item g
 126 Revert current buffer: update information about the displayed
 127 packages/generations and redisplay it.
 128
 129 @item R
 130 Redisplay current buffer (without updating information).
 131
 132 @item C-c C-z
 133 Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}).
 134
 135 @item h
 136 @itemx ?
 137 Describe current mode to see all available bindings.
 138
 139 @end table
 140
 141 @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can
 142 simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own
 143 history.
 144
 145 @emph{Warning:} Name/version pairs cannot be used to identify packages
 146 (because a name is not necessarily unique), so ``guix.el'' uses special
 147 identifiers that live only during a guile session, so if the Guix REPL
 148 was restarted, you may want to revert ``list'' buffer (by pressing
 149 @kbd{g}).
 150
 151 @node emacs List buffer
 152 @subsubsection ``List'' buffer
 153
 154 An interface of a ``list'' buffer is similar to the interface provided
 155 by ``package.el'' (@pxref{Package Menu,,, emacs, The Emacs Editor}).
 156
 157 Default key bindings available for both ``package-list'' and
 158 ``generation-list'' buffers:
 159
 160 @table @kbd
 161 @item m
 162 Mark the current entry.
 163 @item M
 164 Mark all entries.
 165 @item u
 166 Unmark the current entry (with prefix, unmark all entries).
 167 @item @key{DEL}
 168 Unmark backward.
 169 @item S
 170 Sort entries by a specified column.
 171 @end table
 172
 173 A ``package-list'' buffer additionally provides the following bindings:
 174
 175 @table @kbd
 176 @item @key{RET}
 177 Describe marked packages (display available information in a
 178 ``package-info'' buffer).
 179 @item i
 180 Mark "out" of the current package for installation (with prefix, prompt
 181 for output(s) to install).
 182 @item d
 183 Mark all installed outputs of the current package for deletion (with
 184 prefix, prompt for output(s) to delete).
 185 @item U
 186 Mark all installed outputs of the current package for upgrading (with
 187 prefix, prompt for output(s) to upgrade).
 188 @item ^
 189 Mark all obsolete packages for upgrading.
 190 @item x
 191 Execute actions on marked packages.
 192 @end table
 193
 194 A ``generation-list'' buffer additionally provides the following
 195 bindings:
 196
 197 @table @kbd
 198 @item @key{RET}
 199 List packages installed in the current generation.
 200 @item i
 201 Describe marked generations (display available information in a
 202 ``generation-info'' buffer).
 203 @end table
 204
 205 @node emacs Info buffer
 206 @subsubsection ``Info'' buffer
 207
 208 The interface of an ``info'' buffer is similar to the interface of
 209 @code{help-mode} (@pxref{Help Mode,,, emacs, The Emacs Editor}).
 210
 211 ``Info'' buffer contains some buttons (as usual you may use @key{TAB} /
 212 @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,,
 213 emacs, The Emacs Editor}) which can be used to:
 214
 215 @itemize @bullet
 216 @item (in a ``package-info'' buffer)
 217
 218 @itemize @minus
 219 @item install/remove a package;
 220 @item jump to a package location;
 221 @item browse home page of a package;
 222 @item describe packages from ``Inputs'' fields.
 223 @end itemize
 224
 225 @item (in a ``generation-info'' buffer)
 226
 227 @itemize @minus
 228 @item remove a generation;
 229 @item list packages installed in a generation;
 230 @item jump to a generation directory.
 231 @end itemize
 232
 233 @end itemize
 234
 235
 236 @node emacs Configuration
 237 @subsection Configuration
 238
 239 There are many variables you can modify to change the appearance or
 240 behavior of Emacs user interface.  Some of these variables are described
 241 in this section.  Also you can use Custom Interface (@pxref{Easy
 242 Customization,,, emacs, The Emacs Editor}) to explore/set variables (not
 243 all) and faces.
 244
 245 @menu
 246 * Guile and Build Options: emacs Build Options. Specifying how packages are built.
 247 * Keymaps: emacs Keymaps.               Configuring key bindings.
 248 * Appearance: emacs Appearance.         Settings for visual appearance.
 249 @end menu
 250
 251 @node emacs Build Options
 252 @subsubsection Guile and Build Options
 253
 254 @table @code
 255 @item guix-guile-program
 256 If you have some special needs for starting a Guile process, you may set
 257 this variable, for example:
 258
 259 @example
 260 (setq guix-guile-program '("/bin/guile" "--no-auto-compile"))
 261 @end example
 262
 263 @item guix-use-substitutes
 264 Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking
 265 guix build}).
 266
 267 @item guix-dry-run
 268 Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix
 269 build}).
 270
 271 @end table
 272
 273 @node emacs Keymaps
 274 @subsubsection Keymaps
 275
 276 If you want to change default key bindings, use the following keymaps
 277 (@pxref{Init Rebinding,,, emacs, The Emacs Editor}):
 278
 279 @table @code
 280 @item guix-list-mode-map
 281 Parent keymap with general keys for ``list'' buffers.
 282
 283 @item guix-package-list-mode-map
 284 Keymap with specific keys for ``package-list'' buffers.
 285
 286 @item guix-generation-list-mode-map
 287 Keymap with specific keys for ``generation-list'' buffers.
 288
 289 @item guix-info-mode-map
 290 Parent keymap with general keys for ``info'' buffers.
 291
 292 @item guix-package-info-mode-map
 293 Keymap with specific keys for ``package-info'' buffers.
 294
 295 @item guix-generation-info-mode-map
 296 Keymap with specific keys for ``generation-info'' buffers.
 297
 298 @end table
 299
 300 @node emacs Appearance
 301 @subsubsection Appearance
 302
 303 You can change almost any aspect of ``list'' / ``info'' buffers using
 304 the following variables:
 305
 306 @table @code
 307 @item guix-list-column-format
 308 @itemx guix-list-column-titles
 309 @itemx guix-list-column-value-methods
 310 Specify the columns, their names, what and how is displayed in ``list''
 311 buffers.
 312
 313 @item guix-info-displayed-params
 314 @itemx guix-info-insert-methods
 315 @itemx guix-info-ignore-empty-vals
 316 @itemx guix-info-param-title-format
 317 @itemx guix-info-multiline-prefix
 318 @itemx guix-info-indent
 319 @itemx guix-info-fill-column
 320 @itemx guix-info-delimiter
 321 Various settings for ``info'' buffers.
 322
 323 @end table