You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

882 lines
28 KiB

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