From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id 4OUaAeF8fWRXCgAASxT56A (envelope-from ) for ; Mon, 05 Jun 2023 08:12:49 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id gMshAeF8fWSJagEA9RJhRA (envelope-from ) for ; Mon, 05 Jun 2023 08:12:49 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 770117D35 for ; Mon, 5 Jun 2023 08:12:48 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1q63Ru-0006kp-Cx; Mon, 05 Jun 2023 02:12:14 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q63Rr-0006jt-Sg for guix-devel@gnu.org; Mon, 05 Jun 2023 02:12:12 -0400 Received: from mout02.posteo.de ([185.67.36.66]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1q63Rp-0007b5-8I for guix-devel@gnu.org; Mon, 05 Jun 2023 02:12:11 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout02.posteo.de (Postfix) with ESMTPS id 36169240103 for ; Mon, 5 Jun 2023 08:12:04 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.de; s=2017; t=1685945524; bh=zSC0H3pZ2fGWPA2+5WXAV40efMjMTTsT+F8srlp/VJw=; h=From:To:Subject:Date:Message-ID:MIME-Version:From; b=plcKFL7Hij5nqWK8QNxVKf9CQd4Iys6vmClZXn0rVVhje1xbXESKmsSbGs4jCT4Bp Sk6nv9iagAZIqmiXcEds0EbssV6QtGw6IzB7aupL1UYTBcqi3gKpxiB5N0PEk4yOln VSlpgCfmCiEl5JkC3R+Dynt6d3wY4VpeFrDswdX3tTh/AOZ5d0o0f250wsWdZ/5Vl+ QPW6DOiKyRaQaWSACy3gY36vuiygCPJ/wSoMRp/Ry5qOHnCBan8Sj1XTPSAQEmOMg8 yu4aOxOv4v3AcIMkiHz5ORjPhva6qNvSkc1XdEB60icgX6Zw/hGjh3OfymolOIt3fV ipsj9ix+nT+MQ== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4QZNYH4kyJz9rxV; Mon, 5 Jun 2023 08:12:03 +0200 (CEST) From: Mekeor Melire To: guix-devel@gnu.org Subject: Draft new Guix Cookbook section on Emacs Date: Sun, 04 Jun 2023 23:32:44 +0000 Message-ID: <87v8g2saju.fsf@posteo.de> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=185.67.36.66; envelope-from=mekeor@posteo.de; helo=mout02.posteo.de X-Spam_score_int: -28 X-Spam_score: -2.9 X-Spam_bar: -- X-Spam_report: (-2.9 / 5.0 requ) BAYES_00=-1.9, DATE_IN_PAST_06_12=1.543, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: guix-devel-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN ARC-Seal: i=1; s=key1; d=yhetil.org; t=1685945568; a=rsa-sha256; cv=none; b=cWBE81eG6yH5NUdcfuBJTKJSgLEx+O3LCfkoPE9hnPfeUgr+bx11xpWCfS9T5a6AbyTS81 37XxjK2uiODSNkzZD+Y+GtW2ni2jGbUgqzmtC6p1KKhqv2h5dHOUbaL/fLoS6l21gTficv cBU/yTzh6Zm2MiGz19ExcKgXMbceSGP4R7CfitlX0lidjGzSKTYQkNCvMNeR4+bBzxlooJ M8RwJCIZRgv5Ky6d6fScl5N2s399G54/BOEJ1Z9XEiW1uZmgTcP8B/ymO/zA+rrz/AH04z +X93xp3YqDTsblchkVvnZ2JKT+TpyUMtt1PynsH2JJCHT8E8szaNZIpdX5ZwOQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.de header.s=2017 header.b=plcKFL7H; dmarc=pass (policy=none) header.from=posteo.de; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1685945568; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=UB+ShDwZWenqrLTOx9iUrWhKAaJ4IgJEzxJ0N3Uy7Jw=; b=EtI08rBdBP2ZNYxsA0OmxnwiOJsonIQvToI7pR5ySFY7uXWK0/xnef5eTFzPFfJ/5r1O+n Gp8IJPhTlzSjU2y/QTUUZ+pqlKzpu15bgU87pAJqDD99uty0sBV6KKN5yAdc3+7JJdsMUW zVtjNNxz3x8I80yru2hu/sQ+Z3GzSJ35UxQeRjrt6UV6AScjiAGEKBXcZj8wA0dVqvQjT1 B/0eF7WYE4rGPHjgWZsC8abjS3LovLjLtj5zafrzI0jiaZco9liuRT8Zq/g8d7C/mlZMgA xC7Kui+4qXvthMCjxEZ1dQ9Cy6oeC7M/3yrvlUpxKcnrBMkt5ufRMLm7vIWcJA== Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.de header.s=2017 header.b=plcKFL7H; dmarc=pass (policy=none) header.from=posteo.de; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" X-Migadu-Scanner: scn0.migadu.com X-Migadu-Spam-Score: -7.48 X-Spam-Score: -7.48 X-Migadu-Queue-Id: 770117D35 X-TUID: AqtXl7/ro8S+ --=-=-= Content-Type: text/plain; format=flowed Hello :) I'd like to contribute to the Guix Cookbook. The Cookbook is written in Texinfo format but as I'm not fluent in it, I decided I'd first draft my contribution in Org-Mode which I'd later export as Texinfo and adapt appropriately. I'm sorry that this also means that the hereby submitted draft does not come as a Git patch for now. Find below a first draft of a new chapter entitled "Emacs", including two subchapters, "Beginners Guide to the Perfect Setup" and "Mu4e". Regarding the Perfect Setup, I'm convinced that it makes sense to have a more beginner-friendly tutorial supplementing the instructions which are already present in the Guix manual. It's meant to have more background information and more, non-essential configuration tips, as well as details on usage, including keybindings. Regarding emails, in the long-term, I'd also like to contribute a new chapter on how to use the mailing-lists, elaborating on how to get local maildir copies of the mailing-lists with tools like isync/mbsync or public-inbox etc. But that's for the future! I'm looking forward to your feedback. Kindly Mekeor --=-=-= Content-Type: text/x-org; charset=utf-8 Content-Disposition: inline; filename=guix-cookbook-emacs.org Content-Transfer-Encoding: quoted-printable * Emacs ** Beginners Guide to the Perfect Setup # Why this tutorial? The GNU Guix manual includes contains a chapter on "The Perfect Setup" of E= macs for hacking on Guix. It is the primary and main resource on this topic= . In contrast, this tutorial is just a supplement, dedicated towards beginn= ers as it offers more background information, details on usage as well as n= on-essential, optional configuration. # What is Emacs and why is it well suited for Guix? GNU Emacs is a text editor and, at its core, an interpreter of its own Lisp= dialect, Emacs-Lisp. It's well suited for hacking on Guix (and Guix-relate= d) code because of its advanced Lisp editing features and since as part of = the GNU project, it's free software, just like GNU Guix. # Do you have to use Emacs for hacking on Guix? Using Emacs is not a precondition for hacking on Guix(-related) code. For e= xample, there's at least one Guix maintainer who rather uses Vim. But if yo= u're interested in Emacs or already using it, keep on reading. # Installation To install Emacs into your Guix user profile, run: #+begin_src sh guix install emacs #+end_src *** Geiser # What is Geiser? Geiser is a package for GNU Emacs that helps with editing code written in t= he Scheme programming language. In particular, it supports the GNU Guile Sc= heme interpreter on which GNU Guix is heavily based. # Why Geiser? Using Geiser is recommended not only because it enhances your Scheme editin= g experience with features like automatic documentation, but also it works = with the ~guix-devel-mode~ described later on. # Installation To install Geiser into your Guix user profile, run: #+begin_src sh guix install emacs-geiser emacs-geiser-guile #+end_src Afterwards, (re)start Emacs in order to make sure that Geiser finds its way= into Emacs' ~load-path~. **** Load Geiser To load Geiser by default add this to your Emacs initialization file: #+begin_src elisp (require 'geiser) #+end_src Note that this not only loads Geiser but =E2=80=93 through Geiser's autoloa= ds =E2=80=93 also hooks Geiser minor-mode onto ~scheme-mode~. I.e. Geiser w= ill start when you open any Scheme file. **** Geiser Guile Load Path If you maintain a local clone of the Guix source code repository, it alread= y contains a =3D.dir-locals.el=3D file which ensures that the path of your = local clone is added to ~geiser-guile-load-path~ whenever you open a Scheme= file in there. But nevertheless, it makes sense to add the path to your lo= cal Guix repository to ~geiser-guile-load-path~ in your Emacs initializatio= n file so that it's set correctly in other directories as well. Make sure that the compiled files in your local Guix repository are up-to-d= ate. I.e. whenever your local working directory of the repository changes (= for example, after running ~git pull~), rebuild Guix as described in the Gu= ix manual. Otherwise, Guile would auto-compile all Guix sources which leads= to misconfiguration[fn:1] and likely hits Geiser's timeout. Consider havin= g two Git worktree of the Guix repository, keeping one always compiled. If you have other Guix-related source code directories on your machine (and= you want to load Guile modules from there), you need to put those in the ~= geiser-guile-load-path~ variable. (Geiser will then add those paths to Guil= e's ~%load-path~ and ~%load-compiled-path~ variables.) #+begin_src elisp (setq geiser-guile-load-path (list "~/src/guix" "~/src/some/channel")) #+end_src **** REPL Configuration You may find handy to make Geiser automatically start a REPL (read-eval-pri= nt-loop) in the background when a Scheme file is opened: #+begin_src elisp (setq geiser-mode-start-repl-p t) #+end_src If you want to speed up Geiser, let it open a single REPL per project (inst= ead of per file) and forgo version compatibility checks: #+begin_src elisp (setq geiser-repl-per-project-p t) (setq geiser-repl-skip-version-check-p nil) #+end_src **** Using Multiple Schemes If you not only have =3Demacs-geiser-guile=3D installed, but also Geiser ba= ckends for other Scheme implementations, adjust the ~geiser-implementations= -alist~ variable. For example: #+begin_src elisp (setq geiser-implementations-alist '( ((regexp "/minlog/") chez) ((regexp "\\.scm$") guile))) #+end_src *** Emacs-Guix =3Demacs-guix=3D is a package for interacting with Guix through Emacs. It h= as been originally developed by Alex Kost and is now maintained within the = Guix project. It not only offers an interactive interface to Guix features,= but also ships some modes for viewing and editing Guix-related files, whic= h are covered in the following. To install Emacs-Guix into your Guix user profile, run: #+begin_src sh guix install emacs-guix #+end_src **** Guix Development Mode =3Dguix-devel-mode=3D offers Guix-specific syntax highlighting, linting and= loading, by utilizing Geiser. To enable it in all Scheme buffers, put this= in your Emacs initialization file: #+begin_src elisp (require 'guix-devel) (require 'scheme) (add-hook 'scheme-mode-hook #'guix-devel-mode) #+end_src But if you occasionally open Scheme files in Emacs that are unrelated to Gu= ix, you might instead enable ~guix-devel-mode~ conditionally, for example l= ike this: #+begin_src elisp (require 'guix-devel) (require 'scheme) (defun maybe-turn-on-guix-devel-mode () (when (string-match-p "guix" (buffer-file-name)) (guix-devel-mode))) (add-hook 'scheme-mode-hook #'maybe-turn-on-guix-devel-mode) #+end_src **** Other Modes Emacs-Guix ships with a many more mode that are useful when hacking on Guix= , including ~guix-build-log-mode~, ~guix-derivation-mode~ and ~guix-prettif= y-mode~. Check out Emacs-Guix' Info manual for more information. # TODO: perhaps add more usage instructions about these modes here. *** Snippets There are many Emacs packages for managing and inserting code snippets. The= Guix repository includes snippets for two of them: Tempel and Yasnippet. B= oth are distributed through the GNU ELPA (Emacs Lisp Package Archive). Pick and use just one of them. There's no advantage of setting up both snip= pet packages since the Guix repository offers almost equal snippets for the= m. (As of writing, there are slightly more snippets for Tempel.) Generally = speaking, the biggest difference between them is that Tempel uses ~lisp-dat= a-mode~ to define snippets while Yasnippet uses a its own format that embed= s Emacs-Lisp into plain text. For both packages, the list of available snippets depends on the current ma= jor mode. The Guix source code repository offers snippets for ~scheme-mode~= and for editing Git commit messages. **** Tempel To install Tempel into your Guix user profile, run: #+begin_src sh guix install emacs-tempel #+end_src In your Emacs initialization file, load the =3Dtempel=3D feature and add th= e path to Guix' proper Tempel snippets to the ~tempel-path~ variable. #+begin_src elisp (require 'tempel) ;; ensure that tempel-path is a list because it may also be a string: (setq tempel-path (ensure-list tempel-path)) (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*")) #+end_src There are many further configuration options described by Tempel itself. (T= ype =3DC-x P tempel RET=3D (~describe-package~) to read them in Emacs.) The most important commands are ~tempel-complete~ (for completing possibly = incomplete input at point), ~tempel-expand~ (for completing exactly matchin= g input at point), ~tempel-insert~ (for inserting a snippet chosen in minib= uffer). For example, in a Scheme buffer, type =3Dpack=3D and call =3DM-x te= mpel-complete RET=3D. This will replace =3Dpack=3D with a snippet for packa= ge definition. This snippet is interactive. It has some logic implemented i= n it. E.g. when you specify ~git-fetch~ as method for fetching the packages= source code, Tempel automatically adapts the ~uri~ field to a S-expression= around ~git-reference~. By default, you can move point to previous or next= snippet field with =3DM-UP=3D and =3DM-DOWN=3D keys (~tempel-previous~ and= ~tempel-next~) respectively. **** Yasnippet To install Yasnippet into your Guix user profile, run: #+begin_src sh guix install emacs-yasnippet #+end_src In your Emacs initialization file, load the =3Dyasnippet=3D feature; make s= ure the respective snippets directory from your local Guix repository is me= mber of the ~yas-snippet-dirs~ variable; and somehow turn on Yasnippet mode= , e.g. globally. Here's an example: #+begin_src elisp (require 'yasnippet) (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas") (yas-global-mode 1) #+end_src To choose and insert a snippet, type =3DC-c & C-s=3D, bound to ~yas-insert-= snippet~. Snippets have a short "key". When there's a valid Yasnippet key before poin= t, pressing =3DTAB=3D (~yas-expand~) will expand it to the full snippet. E.= g. when editing a Git commit message, you can type =3Da d d TAB=3D to inser= t a snippet that describes the addition of a new package according to Guix'= commit conventions. If you use completion frameworks like Consult.el, Helm or Ivy, search the w= eb for packages that integrate Yasnippet into it. *** Usage Let's assume you opened a Guix-related Scheme file in Emacs and ~scheme-mod= e~, ~geiser-mode~ and ~guix-devel-mode~ are turned on. Let's further assume= ~geiser-autodoc-mode~ has been enabled, as Geiser does by default. To load the Guile module, that is defined by the current file, into the Gei= ser's Guile REPL, type =3DC-c . u=3D which runs ~guix-devel-use-module~. Similarly, when editing a package definition, =3DC-c . l=3D will lint curre= nt package definition at point using =3Dguix lint=3D. Thus, it will also ru= n some security checks and make sure the package builds etc. Now, move the point to Guix-related identifiers and Geiser Autodoc Mode wil= l echo helpful information. For more detailed information on the symbol at = point, type =3DC-c C-d d=3D (or =3DC-c C-d C-d=3D), bound to ~geiser-doc-sy= mbol-at-point~. To view a full list of keybindings, e.g. for linting, type =3DC-h b=3D. ** Mu4e Mu is a tool for dealing with maildirs. Mu4e is integrates Mu into Emacs as= mail reader. To install Mu and Mu4e into your Guix user profile, run: #+begin_src sh guix install mu #+end_src Mu4e includes an /action/ to apply a Git patch that is attached to the emai= l that you are viewing. The action is not enabled by default. In order to e= nable it, put the following in your Emacs initialization file: #+begin_src elisp (add-to-list 'mu4e-view-actions '("apply git patch" . mu4e-action-git-apply-mbox)) #+end_src Now, you can apply the patch by typing =3Da a=3D. * Footnotes [fn:1] Guile might compile the Scheme code into its own cache instead of pu= tting the resulting =3D.go=3D files next to their sources. You might then r= emove the ~/.cache/guile~ directory. --=-=-=--