diff options
author | Matthew Bauer <mjbauer95@gmail.com> | 2017-05-20 21:05:16 -0500 |
---|---|---|
committer | Matthew Bauer <mjbauer95@gmail.com> | 2017-05-20 21:05:16 -0500 |
commit | 64bddb3f1ed85b0f8e8c98f95efffd667596258a (patch) | |
tree | 4728bcf229f0b53287eeb9c278d886745a903e31 | |
parent | aafe99ca90148ed98309715669c973bd2069ecf3 (diff) |
manual: add "Emacs" section to manual
This gives some basics on configuring Emacs within Nix. The
configuration is fairly long just to give a good idea of what’s going
on. I can trim out some of it if it’s not necessary. Note that there
is already a section for Emacs in the NixOS manual. However, this is
aimed at avoiding using modules altogether to make things easier for
non-NixOS users. This configuration should work on NixOS anyway,
however.
Fixes #24243
Fixes #19956
-rw-r--r-- | doc/package-notes.xml | 136 |
1 files changed, 136 insertions, 0 deletions
diff --git a/doc/package-notes.xml b/doc/package-notes.xml index 0f148f5c898a..33a61f31938c 100644 --- a/doc/package-notes.xml +++ b/doc/package-notes.xml @@ -516,4 +516,140 @@ to your configuration, rebuild, and run the game with </section> +<section xml:id="sec-emacs"> + +<title>Emacs</title> + +<section xml:id="sec-emacs-config"> + +<title>Configuring Emacs</title> + +<para> + The Emacs package comes with some extra helpers to make it easier to + configure. <varname>emacsWithPackages</varname> allows you to manage + packages from ELPA. This means that you will not have to install + that packages from within Emacs. For instance, if you wanted to use + <literal>company</literal>, <literal>counsel</literal>, + <literal>flycheck</literal>, <literal>ivy</literal>, + <literal>magit</literal>, <literal>projectile</literal>, and + <literal>use-package</literal> you could use this as a + <filename>~/.config/nixpkgs/config.nix</filename> override: +</para> + +<screen> +{ + packageOverrides = pkgs: with pkgs; { + myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ + company + counsel + flycheck + ivy + magit + projectile + use-package + ])); + } +} +</screen> + +<para> + You can install it like any other packages via <command>nix-env -iA + myEmacs</command>. However, this will only install those packages. + It will not <literal>configure</literal> them for us. To do this, we + need to provide a configuration file. Luckily, it is possible to do + this from within Nix! By modifying the above example, we can make + Emacs load a custom config file. The key is to create a package that + provide a <filename>default.el</filename> file in + <filename>/share/emacs/site-start/</filename>. Emacs knows to load + this file automatically when it starts. +</para> + +<screen> +{ + packageOverrides = pkgs: with pkgs; rec { + myEmacsConfig = writeText "default.el" '' +;; initialize package + +(require 'package) +(package-initialize 'noactivate) +(eval-when-compile + (require 'use-package)) + +;; load some packages + +(use-package company + :bind ("<C-tab>" . company-complete) + :diminish company-mode + :commands (company-mode global-company-mode) + :defer 1 + :config + (global-company-mode)) + +(use-package counsel + :commands (counsel-descbinds) + :bind (([remap execute-extended-command] . counsel-M-x) + ("C-x C-f" . counsel-find-file) + ("C-c g" . counsel-git) + ("C-c j" . counsel-git-grep) + ("C-c k" . counsel-ag) + ("C-x l" . counsel-locate) + ("M-y" . counsel-yank-pop))) + +(use-package flycheck + :defer 2 + :config (global-flycheck-mode)) + +(use-package ivy + :defer 1 + :bind (("C-c C-r" . ivy-resume) + ("C-x C-b" . ivy-switch-buffer) + :map ivy-minibuffer-map + ("C-j" . ivy-call)) + :diminish ivy-mode + :commands ivy-mode + :config + (ivy-mode 1)) + +(use-package magit + :defer + :if (executable-find "git") + :bind (("C-x g" . magit-status) + ("C-x G" . magit-dispatch-popup)) + :init + (setq magit-completing-read-function 'ivy-completing-read)) + +(use-package projectile + :commands projectile-mode + :bind-keymap ("C-c p" . projectile-command-map) + :defer 5 + :config + (projectile-global-mode)) + ''; + myEmacs = emacsWithPackages (epkgs: (with epkgs.melpaStablePackages; [ + (runCommand "default.el" {} '' +mkdir -p $out/share/emacs/site-lisp +cp ${myEmacsConfig} $out/share/emacs/site-lisp/default.el +'') + company + counsel + flycheck + ivy + magit + projectile + use-package + ])); + }; +} +</screen> + +<para> + This provides a fairly full Emacs start file. It will load in + addition to the user's presonal config. You can always disable it by + passing <command>-q</command> to the Emacs command. +</para> + +</section> + +</section> + </chapter> |