| 1 | @node Emacs Interface |
| 2 | @chapter Emacs Interface |
| 3 | |
| 4 | @cindex Emacs |
| 5 | GNU Guix comes with several useful modules (known as ``guix.el'') for |
| 6 | GNU@tie{}Emacs which are intended to make an Emacs user interaction with |
| 7 | Guix convenient and fun. |
| 8 | |
| 9 | @menu |
| 10 | * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. |
| 11 | * Package Management: Emacs Package Management. Managing packages and generations. |
| 12 | * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. |
| 13 | * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. |
| 14 | * Build Log Mode: Emacs Build Log. Highlighting Guix build logs. |
| 15 | * Completions: Emacs Completions. Completing @command{guix} shell command. |
| 16 | * Development: Emacs Development. Tools for Guix developers. |
| 17 | * Hydra: Emacs Hydra. Interface for Guix build farm. |
| 18 | @end menu |
| 19 | |
| 20 | |
| 21 | @node Emacs Initial Setup |
| 22 | @section Initial Setup |
| 23 | |
| 24 | On the Guix System Distribution (@pxref{GNU Distribution}), ``guix.el'' |
| 25 | is ready to use, provided Guix is installed system-wide, which is the |
| 26 | case by default. So if that is what you're using, you can happily skip |
| 27 | this section and read about the fun stuff. |
| 28 | |
| 29 | If you're not yet a happy user of GuixSD, a little bit of setup is needed. |
| 30 | To be able to use ``guix.el'', you need to install the following |
| 31 | packages: |
| 32 | |
| 33 | @itemize |
| 34 | @item |
| 35 | @uref{http://www.gnu.org/software/emacs/, GNU Emacs}, version 24.3 or |
| 36 | later; |
| 37 | |
| 38 | @item |
| 39 | @uref{http://nongnu.org/geiser/, Geiser}, version 0.3 or later: it is |
| 40 | used for interacting with the Guile process. |
| 41 | |
| 42 | @item |
| 43 | @uref{https://github.com/magit/magit/, magit-popup library}. You |
| 44 | already have this library if you use Magit 2.1.0 or later. This library |
| 45 | is an optional dependency---it is required only for @kbd{M-x@tie{}guix} |
| 46 | command (@pxref{Emacs Popup Interface}). |
| 47 | |
| 48 | @end itemize |
| 49 | |
| 50 | When it is done ``guix.el'' may be configured by requiring a special |
| 51 | @code{guix-init} file---i.e., by adding the following code into your |
| 52 | init file (@pxref{Init File,,, emacs, The GNU Emacs Manual}): |
| 53 | |
| 54 | @example |
| 55 | (add-to-list 'load-path "/path/to/directory-with-guix.el") |
| 56 | (require 'guix-init nil t) |
| 57 | @end example |
| 58 | |
| 59 | So the only thing you need to figure out is where the directory with |
| 60 | elisp files for Guix is placed. It depends on how you installed Guix: |
| 61 | |
| 62 | @itemize |
| 63 | @item |
| 64 | If it was installed by a package manager of your distribution or by a |
| 65 | usual @code{./configure && make && make install} command sequence, then |
| 66 | elisp files are placed in a standard directory with Emacs packages |
| 67 | (usually it is @file{/usr/share/emacs/site-lisp/}), which is already in |
| 68 | @code{load-path}, so there is no need to add that directory there. |
| 69 | |
| 70 | @item |
| 71 | If you used a binary installation method (@pxref{Binary Installation}), |
| 72 | then Guix is installed somewhere in the store, so the elisp files are |
| 73 | placed in @file{/gnu/store/@dots{}-guix-0.8.2/share/emacs/site-lisp/} or |
| 74 | alike. However it is not recommended to refer directly to a store |
| 75 | directory. Instead you can install Guix using Guix itself with |
| 76 | @command{guix package -i guix} command (@pxref{Invoking guix package}) |
| 77 | and add @file{~/.guix-profile/share/emacs/site-lisp/} directory to |
| 78 | @code{load-path} variable. |
| 79 | |
| 80 | @item |
| 81 | If you did not install Guix at all and prefer a hacking way |
| 82 | (@pxref{Running Guix Before It Is Installed}), along with augmenting |
| 83 | @code{load-path} you need to set @code{guix-load-path} variable to the |
| 84 | same directory, so your final configuration will look like this: |
| 85 | |
| 86 | @example |
| 87 | (let ((dir "/path/to/your-guix-git-tree/emacs")) |
| 88 | (add-to-list 'load-path dir) |
| 89 | (setq guix-load-path dir)) |
| 90 | (require 'guix-init nil t) |
| 91 | @end example |
| 92 | @end itemize |
| 93 | |
| 94 | By default, along with autoloading (@pxref{Autoload,,, elisp, The GNU |
| 95 | Emacs Lisp Reference Manual}) the main interactive commands for |
| 96 | ``guix.el'' (@pxref{Emacs Commands}), requiring @code{guix-init} will |
| 97 | also autoload commands for the Emacs packages installed in your user |
| 98 | profile. |
| 99 | |
| 100 | To disable automatic loading of installed Emacs packages, set |
| 101 | @code{guix-package-enable-at-startup} variable to @code{nil} before |
| 102 | requiring @code{guix-init}. This variable has the same meaning for |
| 103 | Emacs packages installed with Guix, as @code{package-enable-at-startup} |
| 104 | for the built-in Emacs package system (@pxref{Package Installation,,, |
| 105 | emacs, The GNU Emacs Manual}). |
| 106 | |
| 107 | You can activate Emacs packages installed in your profile whenever you |
| 108 | want using @kbd{M-x@tie{}guix-emacs-load-autoloads}. |
| 109 | |
| 110 | |
| 111 | @node Emacs Package Management |
| 112 | @section Package Management |
| 113 | |
| 114 | Once ``guix.el'' has been successfully configured, you should be able to |
| 115 | use a visual interface for routine package management tasks, pretty much |
| 116 | like the @command{guix package} command (@pxref{Invoking guix package}). |
| 117 | Specifically, it makes it easy to: |
| 118 | |
| 119 | @itemize |
| 120 | @item browse and display packages and generations; |
| 121 | @item search, install, upgrade and remove packages; |
| 122 | @item display packages from previous generations; |
| 123 | @item do some other useful things. |
| 124 | @end itemize |
| 125 | |
| 126 | @menu |
| 127 | * Commands: Emacs Commands. @kbd{M-x guix-@dots{}} |
| 128 | * General information: Emacs General info. Common for both interfaces. |
| 129 | * ``List'' buffer: Emacs List buffer. List-like interface. |
| 130 | * ``Info'' buffer: Emacs Info buffer. Help-like interface. |
| 131 | * Configuration: Emacs Configuration. Configuring the interface. |
| 132 | @end menu |
| 133 | |
| 134 | @node Emacs Commands |
| 135 | @subsection Commands |
| 136 | |
| 137 | All commands for displaying packages and generations use the current |
| 138 | profile, which can be changed with |
| 139 | @kbd{M-x@tie{}guix-set-current-profile}. Alternatively, if you call any |
| 140 | of these commands with prefix argument (@kbd{C-u}), you will be prompted |
| 141 | for a profile just for that command. |
| 142 | |
| 143 | Commands for displaying packages: |
| 144 | |
| 145 | @table @kbd |
| 146 | |
| 147 | @item M-x guix-all-available-packages |
| 148 | @itemx M-x guix-newest-available-packages |
| 149 | Display all/newest available packages. |
| 150 | |
| 151 | @item M-x guix-installed-packages |
| 152 | Display all installed packages. |
| 153 | |
| 154 | @item M-x guix-obsolete-packages |
| 155 | Display obsolete packages (the packages that are installed in a profile |
| 156 | but cannot be found among available packages). |
| 157 | |
| 158 | @item M-x guix-search-by-name |
| 159 | Display package(s) with the specified name. |
| 160 | |
| 161 | @item M-x guix-search-by-regexp |
| 162 | Search for packages by a specified regexp. By default ``name'', |
| 163 | ``synopsis'' and ``description'' of the packages will be searched. This |
| 164 | can be changed by modifying @code{guix-package-search-params} variable. |
| 165 | |
| 166 | @end table |
| 167 | |
| 168 | By default, these commands display each output on a separate line. If |
| 169 | you prefer to see a list of packages---i.e., a list with a package per |
| 170 | line, use the following setting: |
| 171 | |
| 172 | @example |
| 173 | (setq guix-package-list-type 'package) |
| 174 | @end example |
| 175 | |
| 176 | Commands for displaying generations: |
| 177 | |
| 178 | @table @kbd |
| 179 | |
| 180 | @item M-x guix-generations |
| 181 | List all the generations. |
| 182 | |
| 183 | @item M-x guix-last-generations |
| 184 | List the @var{N} last generations. You will be prompted for the number |
| 185 | of generations. |
| 186 | |
| 187 | @item M-x guix-generations-by-time |
| 188 | List generations matching time period. You will be prompted for the |
| 189 | period using Org mode time prompt based on Emacs calendar (@pxref{The |
| 190 | date/time prompt,,, org, The Org Manual}). |
| 191 | |
| 192 | @end table |
| 193 | |
| 194 | Analogously on GuixSD you can also display system generations: |
| 195 | |
| 196 | @table @kbd |
| 197 | @item M-x guix-system-generations |
| 198 | @item M-x guix-last-system-generations |
| 199 | @item M-x guix-system-generations-by-time |
| 200 | @end table |
| 201 | |
| 202 | You can also invoke the @command{guix pull} command (@pxref{Invoking |
| 203 | guix pull}) from Emacs using: |
| 204 | |
| 205 | @table @kbd |
| 206 | @item M-x guix-pull |
| 207 | With @kbd{C-u}, make it verbose. |
| 208 | @end table |
| 209 | |
| 210 | Once @command{guix pull} has succeeded, the Guix REPL is restared. This |
| 211 | allows you to keep using the Emacs interface with the updated Guix. |
| 212 | |
| 213 | @node Emacs General info |
| 214 | @subsection General information |
| 215 | |
| 216 | The following keys are available for both ``list'' and ``info'' types of |
| 217 | buffers: |
| 218 | |
| 219 | @table @kbd |
| 220 | @item l |
| 221 | @itemx r |
| 222 | Go backward/forward by the history of the displayed results (this |
| 223 | history is similar to the history of the Emacs @code{help-mode} or |
| 224 | @code{Info-mode}). |
| 225 | |
| 226 | @item g |
| 227 | Revert current buffer: update information about the displayed |
| 228 | packages/generations and redisplay it. |
| 229 | |
| 230 | @item R |
| 231 | Redisplay current buffer (without updating information). |
| 232 | |
| 233 | @item M |
| 234 | Apply manifest to the current profile or to a specified profile, if |
| 235 | prefix argument is used. This has the same meaning as @code{--manifest} |
| 236 | option (@pxref{Invoking guix package}). |
| 237 | |
| 238 | @item C-c C-z |
| 239 | @cindex REPL |
| 240 | @cindex read-eval-print loop |
| 241 | Go to the Guix REPL (@pxref{The REPL,,, geiser, Geiser User Manual}). |
| 242 | |
| 243 | @item h |
| 244 | @itemx ? |
| 245 | Describe current mode to see all available bindings. |
| 246 | |
| 247 | @end table |
| 248 | |
| 249 | @emph{Hint:} If you need several ``list'' or ``info'' buffers, you can |
| 250 | simlpy @kbd{M-x clone-buffer} them, and each buffer will have its own |
| 251 | history. |
| 252 | |
| 253 | @emph{Warning:} Name/version pairs cannot be used to identify packages |
| 254 | (because a name is not necessarily unique), so ``guix.el'' uses special |
| 255 | identifiers that live only during a guile session, so if the Guix REPL |
| 256 | was restarted, you may want to revert ``list'' buffer (by pressing |
| 257 | @kbd{g}). |
| 258 | |
| 259 | @node Emacs List buffer |
| 260 | @subsection ``List'' buffer |
| 261 | |
| 262 | An interface of a ``list'' buffer is similar to the interface provided |
| 263 | by ``package.el'' (@pxref{Package Menu,,, emacs, The GNU Emacs Manual}). |
| 264 | |
| 265 | Default key bindings available for both ``package-list'' and |
| 266 | ``generation-list'' buffers: |
| 267 | |
| 268 | @table @kbd |
| 269 | @item m |
| 270 | Mark the current entry (with prefix, mark all entries). |
| 271 | @item u |
| 272 | Unmark the current entry (with prefix, unmark all entries). |
| 273 | @item @key{DEL} |
| 274 | Unmark backward. |
| 275 | @item S |
| 276 | Sort entries by a specified column. |
| 277 | @end table |
| 278 | |
| 279 | A ``package-list'' buffer additionally provides the following bindings: |
| 280 | |
| 281 | @table @kbd |
| 282 | @item @key{RET} |
| 283 | Describe marked packages (display available information in a |
| 284 | ``package-info'' buffer). |
| 285 | @item i |
| 286 | Mark the current package for installation. |
| 287 | @item d |
| 288 | Mark the current package for deletion. |
| 289 | @item U |
| 290 | Mark the current package for upgrading. |
| 291 | @item ^ |
| 292 | Mark all obsolete packages for upgrading. |
| 293 | @item e |
| 294 | Edit the definition of the curent package (go to its location). This is |
| 295 | similar to @command{guix edit} command (@pxref{Invoking guix edit}), but |
| 296 | for opening a package recipe in the current Emacs instance. |
| 297 | @item x |
| 298 | Execute actions on the marked packages. |
| 299 | @item B |
| 300 | Display latest builds of the current package (@pxref{Emacs Hydra}). |
| 301 | @end table |
| 302 | |
| 303 | A ``generation-list'' buffer additionally provides the following |
| 304 | bindings: |
| 305 | |
| 306 | @table @kbd |
| 307 | @item @key{RET} |
| 308 | List packages installed in the current generation. |
| 309 | @item i |
| 310 | Describe marked generations (display available information in a |
| 311 | ``generation-info'' buffer). |
| 312 | @item s |
| 313 | Switch profile to the current generation. |
| 314 | @item d |
| 315 | Mark the current generation for deletion (with prefix, mark all |
| 316 | generations). |
| 317 | @item x |
| 318 | Execute actions on the marked generations---i.e., delete generations. |
| 319 | @item e |
| 320 | Run Ediff (@pxref{Top,,, ediff, The Ediff Manual}) on package outputs |
| 321 | installed in the 2 marked generations. With prefix argument, run Ediff |
| 322 | on manifests of the marked generations. |
| 323 | @item D |
| 324 | @itemx = |
| 325 | Run Diff (@pxref{Diff Mode,,, emacs, The GNU Emacs Manual}) on package |
| 326 | outputs installed in the 2 marked generations. With prefix argument, |
| 327 | run Diff on manifests of the marked generations. |
| 328 | @item + |
| 329 | List package outputs added to the latest marked generation comparing |
| 330 | with another marked generation. |
| 331 | @item - |
| 332 | List package outputs removed from the latest marked generation comparing |
| 333 | with another marked generation. |
| 334 | @end table |
| 335 | |
| 336 | @node Emacs Info buffer |
| 337 | @subsection ``Info'' buffer |
| 338 | |
| 339 | The interface of an ``info'' buffer is similar to the interface of |
| 340 | @code{help-mode} (@pxref{Help Mode,,, emacs, The GNU Emacs Manual}). |
| 341 | |
| 342 | ``Info'' buffer contains some buttons (as usual you may use @key{TAB} / |
| 343 | @kbd{S-@key{TAB}} to move between buttons---@pxref{Mouse References,,, |
| 344 | emacs, The GNU Emacs Manual}) which can be used to: |
| 345 | |
| 346 | @itemize @bullet |
| 347 | @item (in a ``package-info'' buffer) |
| 348 | |
| 349 | @itemize @minus |
| 350 | @item install/remove a package; |
| 351 | @item jump to a package location; |
| 352 | @item browse home page of a package; |
| 353 | @item describe packages from ``Inputs'' fields. |
| 354 | @end itemize |
| 355 | |
| 356 | @item (in a ``generation-info'' buffer) |
| 357 | |
| 358 | @itemize @minus |
| 359 | @item remove a generation; |
| 360 | @item switch to a generation; |
| 361 | @item list packages installed in a generation; |
| 362 | @item jump to a generation directory. |
| 363 | @end itemize |
| 364 | |
| 365 | @end itemize |
| 366 | |
| 367 | It is also possible to copy a button label (a link to an URL or a file) |
| 368 | by pressing @kbd{c} on a button. |
| 369 | |
| 370 | |
| 371 | @node Emacs Configuration |
| 372 | @subsection Configuration |
| 373 | |
| 374 | There are many variables you can modify to change the appearance or |
| 375 | behavior of Emacs user interface. Some of these variables are described |
| 376 | in this section. Also you can use Custom Interface (@pxref{Easy |
| 377 | Customization,,, emacs, The GNU Emacs Manual}) to explore/set variables |
| 378 | (not all) and faces. |
| 379 | |
| 380 | @menu |
| 381 | * Guile and Build Options: Emacs Build Options. Specifying how packages are built. |
| 382 | * Buffer Names: Emacs Buffer Names. Names of Guix buffers. |
| 383 | * Keymaps: Emacs Keymaps. Configuring key bindings. |
| 384 | * Appearance: Emacs Appearance. Settings for visual appearance. |
| 385 | @end menu |
| 386 | |
| 387 | @node Emacs Build Options |
| 388 | @subsubsection Guile and Build Options |
| 389 | |
| 390 | @table @code |
| 391 | @item guix-guile-program |
| 392 | If you have some special needs for starting a Guile process, you may set |
| 393 | this variable, for example: |
| 394 | |
| 395 | @example |
| 396 | (setq guix-guile-program '("/bin/guile" "--no-auto-compile")) |
| 397 | @end example |
| 398 | |
| 399 | @item guix-use-substitutes |
| 400 | Has the same meaning as @code{--no-substitutes} option (@pxref{Invoking |
| 401 | guix build}). |
| 402 | |
| 403 | @item guix-dry-run |
| 404 | Has the same meaning as @code{--dry-run} option (@pxref{Invoking guix |
| 405 | build}). |
| 406 | |
| 407 | @end table |
| 408 | |
| 409 | @node Emacs Buffer Names |
| 410 | @subsubsection Buffer Names |
| 411 | |
| 412 | Default names of ``guix.el'' buffers (``*Guix@tie{}@dots{}*'') may be |
| 413 | changed with the following variables: |
| 414 | |
| 415 | @table @code |
| 416 | @item guix-package-list-buffer-name |
| 417 | @item guix-output-list-buffer-name |
| 418 | @item guix-generation-list-buffer-name |
| 419 | @item guix-package-info-buffer-name |
| 420 | @item guix-output-info-buffer-name |
| 421 | @item guix-generation-info-buffer-name |
| 422 | @item guix-repl-buffer-name |
| 423 | @item guix-internal-repl-buffer-name |
| 424 | @end table |
| 425 | |
| 426 | By default, the name of a profile is also displayed in a ``list'' or |
| 427 | ``info'' buffer name. To change this behavior, use |
| 428 | @code{guix-ui-buffer-name-function} variable. |
| 429 | |
| 430 | For example, if you want to display all types of results in a single |
| 431 | buffer (in such case you will probably use a history (@kbd{l}/@kbd{r}) |
| 432 | extensively), you may do it like this: |
| 433 | |
| 434 | @example |
| 435 | (let ((name "Guix Universal")) |
| 436 | (setq |
| 437 | guix-package-list-buffer-name name |
| 438 | guix-output-list-buffer-name name |
| 439 | guix-generation-list-buffer-name name |
| 440 | guix-package-info-buffer-name name |
| 441 | guix-output-info-buffer-name name |
| 442 | guix-generation-info-buffer-name name)) |
| 443 | @end example |
| 444 | |
| 445 | @node Emacs Keymaps |
| 446 | @subsubsection Keymaps |
| 447 | |
| 448 | If you want to change default key bindings, use the following keymaps |
| 449 | (@pxref{Init Rebinding,,, emacs, The GNU Emacs Manual}): |
| 450 | |
| 451 | @table @code |
| 452 | @item guix-buffer-map |
| 453 | Parent keymap with general keys for any buffer type. |
| 454 | |
| 455 | @item guix-ui-map |
| 456 | Parent keymap with general keys for buffers used for Guix package |
| 457 | management (for packages, outputs and generations). |
| 458 | |
| 459 | @item guix-list-mode-map |
| 460 | Parent keymap with general keys for ``list'' buffers. |
| 461 | |
| 462 | @item guix-package-list-mode-map |
| 463 | Keymap with specific keys for ``package-list'' buffers. |
| 464 | |
| 465 | @item guix-output-list-mode-map |
| 466 | Keymap with specific keys for ``output-list'' buffers. |
| 467 | |
| 468 | @item guix-generation-list-mode-map |
| 469 | Keymap with specific keys for ``generation-list'' buffers. |
| 470 | |
| 471 | @item guix-info-mode-map |
| 472 | Parent keymap with general keys for ``info'' buffers. |
| 473 | |
| 474 | @item guix-package-info-mode-map |
| 475 | Keymap with specific keys for ``package-info'' buffers. |
| 476 | |
| 477 | @item guix-output-info-mode-map |
| 478 | Keymap with specific keys for ``output-info'' buffers. |
| 479 | |
| 480 | @item guix-generation-info-mode-map |
| 481 | Keymap with specific keys for ``generation-info'' buffers. |
| 482 | |
| 483 | @item guix-info-button-map |
| 484 | Keymap with keys available when a point is placed on a button. |
| 485 | |
| 486 | @end table |
| 487 | |
| 488 | @node Emacs Appearance |
| 489 | @subsubsection Appearance |
| 490 | |
| 491 | You can change almost any aspect of ``list'' / ``info'' buffers using |
| 492 | the following variables (@dfn{ENTRY-TYPE} means @code{package}, |
| 493 | @code{output} or @code{generation}): |
| 494 | |
| 495 | @table @code |
| 496 | @item guix-ENTRY-TYPE-list-format |
| 497 | @itemx guix-ENTRY-TYPE-list-titles |
| 498 | Specify the columns, their names, what and how is displayed in ``list'' |
| 499 | buffers. |
| 500 | |
| 501 | @item guix-ENTRY-TYPE-info-format |
| 502 | @itemx guix-ENTRY-TYPE-info-titles |
| 503 | @itemx guix-info-ignore-empty-values |
| 504 | @itemx guix-info-param-title-format |
| 505 | @itemx guix-info-multiline-prefix |
| 506 | @itemx guix-info-indent |
| 507 | @itemx guix-info-fill |
| 508 | @itemx guix-info-delimiter |
| 509 | Various settings for ``info'' buffers. |
| 510 | |
| 511 | @end table |
| 512 | |
| 513 | |
| 514 | @node Emacs Popup Interface |
| 515 | @section Popup Interface |
| 516 | |
| 517 | If you ever used Magit, you know what ``popup interface'' is |
| 518 | (@pxref{Top,,, magit-popup, Magit-Popup User Manual}). Even if you are |
| 519 | not acquainted with Magit, there should be no worries as it is very |
| 520 | intuitive. |
| 521 | |
| 522 | So @kbd{M-x@tie{}guix} command provides a top-level popup interface for |
| 523 | all available guix commands. When you select an option, you'll be |
| 524 | prompted for a value in the minibuffer. Many values have completions, |
| 525 | so don't hesitate to press @key{TAB} key. Multiple values (for example, |
| 526 | packages or lint checkers) should be separated by commas. |
| 527 | |
| 528 | After specifying all options and switches for a command, you may choose |
| 529 | one of the available actions. The following default actions are |
| 530 | available for all commands: |
| 531 | |
| 532 | @itemize |
| 533 | |
| 534 | @item |
| 535 | Run the command in the Guix REPL. It is faster than running |
| 536 | @code{guix@tie{}@dots{}} command directly in shell, as there is no |
| 537 | need to run another guile process and to load required modules there. |
| 538 | |
| 539 | @item |
| 540 | Run the command in a shell buffer. You can set |
| 541 | @code{guix-run-in-shell-function} variable to fine tune the shell buffer |
| 542 | you want to use. |
| 543 | |
| 544 | @item |
| 545 | Add the command line to the kill ring (@pxref{Kill Ring,,, emacs, The |
| 546 | GNU Emacs Manual}). |
| 547 | |
| 548 | @end itemize |
| 549 | |
| 550 | Several commands (@command{guix graph}, @command{guix system dmd-graph} |
| 551 | and @command{guix system extension-graph}) also have a ``View graph'' |
| 552 | action, which allows you to view a generated graph using @command{dot} |
| 553 | command (specified by @code{guix-dot-program} variable). By default a |
| 554 | PNG file will be saved in @file{/tmp} directory and will be opened |
| 555 | directly in Emacs. This behavior may be changed with the following |
| 556 | variables: |
| 557 | |
| 558 | @table @code |
| 559 | |
| 560 | @item guix-find-file-function |
| 561 | Function used to open a generated graph. If you want to open a graph in |
| 562 | an external program, you can do it by modifying this variable---for |
| 563 | example, you can use a functionality provided by the Org Mode |
| 564 | (@pxref{Top,,, org, The Org Manual}): |
| 565 | |
| 566 | @example |
| 567 | (setq guix-find-file-function 'org-open-file) |
| 568 | (add-to-list 'org-file-apps '("\\.png\\'" . "sxiv %s")) |
| 569 | @end example |
| 570 | |
| 571 | @item guix-dot-default-arguments |
| 572 | Command line arguments to run @command{dot} command. If you change an |
| 573 | output format (for example, into @code{-Tpdf}), you also need to change |
| 574 | the next variable. |
| 575 | |
| 576 | @item guix-dot-file-name-function |
| 577 | Function used to define a name of the generated graph file. Default |
| 578 | name is @file{/tmp/guix-emacs-graph-XXXXXX.png}. |
| 579 | |
| 580 | @end table |
| 581 | |
| 582 | So, for example, if you want to generate and open a PDF file in your |
| 583 | Emacs, you may change the settings like this: |
| 584 | |
| 585 | @example |
| 586 | (defun my-guix-pdf-graph () |
| 587 | "/tmp/my-current-guix-graph.pdf") |
| 588 | |
| 589 | (setq guix-dot-default-arguments '("-Tpdf") |
| 590 | guix-dot-file-name-function 'my-guix-pdf-graph) |
| 591 | @end example |
| 592 | |
| 593 | |
| 594 | @node Emacs Prettify |
| 595 | @section Guix Prettify Mode |
| 596 | |
| 597 | GNU@tie{}Guix also comes with ``guix-prettify.el''. It provides a minor |
| 598 | mode for abbreviating store file names by replacing hash sequences of |
| 599 | symbols with ``@dots{}'': |
| 600 | |
| 601 | @example |
| 602 | /gnu/store/72f54nfp6g1hz873w8z3gfcah0h4nl9p-foo-0.1 |
| 603 | @result{} /gnu/store/…-foo-0.1 |
| 604 | @end example |
| 605 | |
| 606 | Once you set up ``guix.el'' (@pxref{Emacs Initial Setup}), the following |
| 607 | commands become available: |
| 608 | |
| 609 | @table @kbd |
| 610 | |
| 611 | @item M-x guix-prettify-mode |
| 612 | Enable/disable prettifying for the current buffer. |
| 613 | |
| 614 | @item M-x global-guix-prettify-mode |
| 615 | Enable/disable prettifying globally. |
| 616 | |
| 617 | @end table |
| 618 | |
| 619 | To automatically enable @code{guix-prettify-mode} globally on Emacs |
| 620 | start, add the following line to your init file: |
| 621 | |
| 622 | @example |
| 623 | (global-guix-prettify-mode) |
| 624 | @end example |
| 625 | |
| 626 | If you want to enable it only for specific major modes, add it to the |
| 627 | mode hooks (@pxref{Hooks,,, emacs, The GNU Emacs Manual}), for example: |
| 628 | |
| 629 | @example |
| 630 | (add-hook 'shell-mode-hook 'guix-prettify-mode) |
| 631 | (add-hook 'dired-mode-hook 'guix-prettify-mode) |
| 632 | @end example |
| 633 | |
| 634 | |
| 635 | @node Emacs Build Log |
| 636 | @section Build Log Mode |
| 637 | |
| 638 | GNU@tie{}Guix provides major and minor modes for highlighting build |
| 639 | logs. So when you have a file with a package build output---for |
| 640 | example, a file returned by @command{guix build --log-file @dots{}} |
| 641 | command (@pxref{Invoking guix build}), you may call @kbd{M-x |
| 642 | guix-build-log-mode} command in the buffer with this file. This major |
| 643 | mode highlights some lines specific to build output and provides the |
| 644 | following key bindings: |
| 645 | |
| 646 | @table @kbd |
| 647 | |
| 648 | @item M-n |
| 649 | Move to the next build phase. |
| 650 | |
| 651 | @item M-p |
| 652 | Move to the previous build phase. |
| 653 | |
| 654 | @item @key{TAB} |
| 655 | Toggle (show/hide) the body of the current build phase. |
| 656 | |
| 657 | @item S-@key{TAB} |
| 658 | Toggle (show/hide) the bodies of all build phases. |
| 659 | |
| 660 | @end table |
| 661 | |
| 662 | There is also @kbd{M-x guix-build-log-minor-mode} which also provides |
| 663 | the same highlighting and the same key bindings as the major mode, but |
| 664 | prefixed with @kbd{C-c}. By default, this minor mode is enabled in |
| 665 | shell buffers (@pxref{Interactive Shell,,, emacs, The GNU Emacs |
| 666 | Manual}). If you don't like it, set |
| 667 | @code{guix-build-log-minor-mode-activate} to nil. |
| 668 | |
| 669 | |
| 670 | @node Emacs Completions |
| 671 | @section Shell Completions |
| 672 | |
| 673 | Another feature that becomes available after configuring Emacs interface |
| 674 | (@pxref{Emacs Initial Setup}) is completing of @command{guix} |
| 675 | subcommands, options, packages and other things in @code{shell} |
| 676 | (@pxref{Interactive Shell,,, emacs, The GNU Emacs Manual}) and |
| 677 | @code{eshell} (@pxref{Top,,, eshell, Eshell: The Emacs Shell}). |
| 678 | |
| 679 | It works the same way as other completions do. Just press @key{TAB} |
| 680 | when your intuition tells you. |
| 681 | |
| 682 | And here are some examples, where pressing @key{TAB} may complete |
| 683 | something: |
| 684 | |
| 685 | @itemize @w{} |
| 686 | |
| 687 | @item @code{guix pa}@key{TAB} |
| 688 | @item @code{guix package -}@key{TAB} |
| 689 | @item @code{guix package --}@key{TAB} |
| 690 | @item @code{guix package -i gei}@key{TAB} |
| 691 | @item @code{guix build -L/tm}@key{TAB} |
| 692 | @item @code{guix build --sy}@key{TAB} |
| 693 | @item @code{guix build --system=i}@key{TAB} |
| 694 | @item @code{guix system rec}@key{TAB} |
| 695 | @item @code{guix lint --checkers=sy}@key{TAB} |
| 696 | @item @code{guix lint --checkers=synopsis,des}@key{TAB} |
| 697 | |
| 698 | @end itemize |
| 699 | |
| 700 | |
| 701 | @node Emacs Development |
| 702 | @section Development |
| 703 | |
| 704 | By default, when you open a Scheme file, @code{guix-devel-mode} will be |
| 705 | activated (if you don't want it, set @code{guix-devel-activate-mode} to |
| 706 | nil). This minor mode provides the following key bindings: |
| 707 | |
| 708 | @table @kbd |
| 709 | |
| 710 | @item C-c . k |
| 711 | Copy the name of the current Guile module into kill ring |
| 712 | (@code{guix-devel-copy-module-as-kill}). |
| 713 | |
| 714 | @item C-c . u |
| 715 | Use the current Guile module. Often after opening a Scheme file, you |
| 716 | want to use a module it defines, so you switch to the Geiser REPL and |
| 717 | write @code{,use (some module)} there. You may just use this command |
| 718 | instead (@code{guix-devel-use-module}). |
| 719 | |
| 720 | @item C-c . b |
| 721 | Build a package defined by the current variable definition. The |
| 722 | building process is run in the current Geiser REPL. If you modified the |
| 723 | current package definition, don't forget to reevaluate it before calling |
| 724 | this command---for example, with @kbd{C-M-x} (@pxref{To eval or not to |
| 725 | eval,,, geiser, Geiser User Manual}) |
| 726 | (@code{guix-devel-build-package-definition}). |
| 727 | |
| 728 | @item C-c . s |
| 729 | Build a source derivation of the package defined by the current variable |
| 730 | definition. This command has the same meaning as @code{guix build -S} |
| 731 | shell command (@pxref{Invoking guix build}) |
| 732 | (@code{guix-devel-build-package-source}). |
| 733 | |
| 734 | @item C-c . l |
| 735 | Lint (check) a package defined by the current variable definition |
| 736 | (@pxref{Invoking guix lint}) (@code{guix-devel-lint-package}). |
| 737 | |
| 738 | @end table |
| 739 | |
| 740 | Unluckily, there is a limitation related to long-running REPL commands. |
| 741 | When there is a running process in a Geiser REPL, you are not supposed |
| 742 | to evaluate anything in a scheme buffer, because this will ``freeze'' |
| 743 | the REPL: it will stop producing any output (however, the evaluating |
| 744 | process will continue---you will just not see any progress anymore). Be |
| 745 | aware: even moving the point in a scheme buffer may ``break'' the REPL |
| 746 | if Autodoc (@pxref{Autodoc and friends,,, geiser, Geiser User Manual}) |
| 747 | is enabled (which is the default). |
| 748 | |
| 749 | So you have to postpone editing your scheme buffers until the running |
| 750 | evaluation will be finished in the REPL. |
| 751 | |
| 752 | Alternatively, to avoid this limitation, you may just run another Geiser |
| 753 | REPL, and while something is being evaluated in the previous REPL, you |
| 754 | can continue editing a scheme file with the help of the current one. |
| 755 | |
| 756 | |
| 757 | @node Emacs Hydra |
| 758 | @section Hydra |
| 759 | |
| 760 | The continuous integration server at @code{hydra.gnu.org} builds all |
| 761 | the distribution packages on the supported architectures and serves |
| 762 | them as substitutes (@pxref{Substitutes}). Continuous integration is |
| 763 | currently orchestrated by @uref{https://nixos.org/hydra/, Hydra}. |
| 764 | |
| 765 | This section describes an Emacs interface to query Hydra to know the |
| 766 | build status of specific packages, discover recent and ongoing builds, |
| 767 | view build logs, and so on. This interface is mostly the same as the |
| 768 | ``list''/``info'' interface for displaying packages and generations |
| 769 | (@pxref{Emacs Package Management}). |
| 770 | |
| 771 | The following commands are available: |
| 772 | |
| 773 | @table @kbd |
| 774 | |
| 775 | @item M-x guix-hydra-latest-builds |
| 776 | Display latest failed or successful builds (you will be prompted for a |
| 777 | number of builds). With @kbd{C-u}, you will also be prompted for other |
| 778 | parameters (project, jobset, job and system). |
| 779 | |
| 780 | @item M-x guix-hydra-queued-builds |
| 781 | Display scheduled or currently running builds (you will be prompted for |
| 782 | a number of builds). |
| 783 | |
| 784 | @item M-x guix-hydra-jobsets |
| 785 | Display available jobsets (you will be prompted for a project). |
| 786 | |
| 787 | @end table |
| 788 | |
| 789 | In a list of builds you can press @kbd{L} key to display a build log of |
| 790 | the current build. Also both a list of builds and a list of jobsets |
| 791 | provide @kbd{B} key to display latest builds of the current job or |
| 792 | jobset (don't forget about @kbd{C-u}). |