| | 1 | <!DOCTYPE html> |
| | 2 | <meta charset="utf-8"> |
| | 3 | |
| | 4 | # Setup Instructions for `emacs` |
| | 5 | |
| | 6 | Created by [Steven Baltakatei Sandoval][bktei_2020_homepage] on 2020-04-16T23:13Z under a [CC BY-SA 4.0][cc_20131125_bysa] license and last updated on 2020-04-17T02:58Z. |
| | 7 | |
| | 8 | ## 1. Summary |
| | 9 | |
| | 10 | Emacs is a command line editor. This document contains instructions and files required to install and customize Emacs on GNU/Linux Debian 10 machines. |
| | 11 | |
| | 12 | ### 1.1. File list |
| | 13 | |
| | 14 | ./config-shared/emacs/INSTRUCTIONS.md # These setup instructions |
| | 15 | ./config-shared/emacs/home/.emacs.d/init.el # enables MELPA repository |
| | 16 | ./config-shared/emacs/home/.config/systemd/user/emacs.service # required for automatic daemon startup |
| | 17 | ./config-shared/emacs/home/.bash_aliases.appendme # contains alias for use with emacs daemon |
| | 18 | |
| | 19 | ## 2. Instructions |
| | 20 | |
| | 21 | ### 2.1. Install `emacs` package |
| | 22 | |
| | 23 | #### 2.1.a. Typical Debian install |
| | 24 | |
| | 25 | Use `$ sudo apt-get install emacs` to install `emacs`. |
| | 26 | |
| | 27 | #### 2.1.b. Headless Debian install (no GUI) |
| | 28 | |
| | 29 | Use `$ sudo apt-get install emacs-nox` to install `emacs` without an X window manager. This may be useful if emacs is to be used via command-line only such as a machine without a monitor to which a use connects via `ssh`. |
| | 30 | |
| | 31 | ### 2.2. Enable MELPA package repository |
| | 32 | |
| | 33 | MELPA is a package repository for packages that add functionality to `emacs`. Detailed instructions for installing it may be found at melpa.org.<sup>[[1]](#melpa_2019_setupinst)</sup> |
| | 34 | |
| | 35 | #### 2.2.a. Typical install |
| | 36 | |
| | 37 | Create and/or edit the `~/.emacs.d/init.el` file to include the following text elisp code: |
| | 38 | |
| | 39 | (require 'package) |
| | 40 | (let* ((no-ssl (and (memq system-type '(windows-nt ms-dos)) |
| | 41 | (not (gnutls-available-p)))) |
| | 42 | (proto (if no-ssl "http" "https"))) |
| | 43 | (when no-ssl (warn "\ |
| | 44 | Your version of Emacs does not support SSL connections, |
| | 45 | which is unsafe because it allows man-in-the-middle attacks. |
| | 46 | There are two things you can do about this warning: |
| | 47 | 1. Install an Emacs version that does support SSL and be safe. |
| | 48 | 2. Remove this warning from your init file so you won't see it again.")) |
| | 49 | (add-to-list 'package-archives (cons "melpa" (concat proto "://melpa.org/packages/")) t) |
| | 50 | ;; Comment/uncomment this line to enable MELPA Stable if desired. See `package-archive-priorities` |
| | 51 | ;; and `package-pinned-packages`. Most users will not need or want to do this. |
| | 52 | ;;(add-to-list 'package-archives (cons "melpa-stable" (concat proto "://stable.melpa.org/packages/")) t) |
| | 53 | ) |
| | 54 | (package-initialize) |
| | 55 | |
| | 56 | A copy of this text is contained within the `./config-shared/emacs/home/.emacs.d/init.el` file in this repository. A command to copy this code to a completely new system is below. |
| | 57 | |
| | 58 | $ mkdir ~/.emacs.d |
| | 59 | $ cp ./config-shared/emacs/home/.emacs.d/init.el ~/.emacs.d/init.el |
| | 60 | |
| | 61 | Run `M-x package-refresh-contents` (can be run from bash via `$ emacs -nw --eval '(progn (package-refresh-contents) (kill-emacs))'`) to download MELPA package list.<sup>[[2]](#se_20161221_emacsclimultieval)</sup> |
| | 62 | |
| | 63 | ### 2.3. Configure `emacs` daemon and `emacsclient` |
| | 64 | |
| | 65 | A convenient way to share buffers between different shells (ex: across guake and Terminal) is to edit files using multiple instances of `emacsclient`<sup>[[4]](#emacswiki_20200325_emacsclient)</sup> which each communicate with a single instance of `emacs --daemon`<sup>[[3]](#emacswiki_20200408_emacsdaemon)</sup>. An instance of `emacsclient` running in `guake` may crash due to a problem with `guake` but the text buffer being edited by the user will not be lost since it is maintained by `emacs --daemon`. To regain access to the buffer, one must only start another instance of `emacsclient` and switch to the buffer (ex: via `C-x b`). |
| | 66 | |
| | 67 | #### 2.3.a. Create `emacs` daemon as a user service. |
| | 68 | |
| | 69 | Create the `~/.config/systemd/user/emacs.service` file to be the following text: |
| | 70 | |
| | 71 | [Unit] |
| | 72 | Description=Emacs text editor |
| | 73 | Documentation=info:emacs man:emacs(1) https://gnu.org/software/emacs/ |
| | 74 | |
| | 75 | [Service] |
| | 76 | Type=forking |
| | 77 | ExecStart=/usr/bin/emacs --daemon |
| | 78 | ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)" |
| | 79 | Encopy itvironment=SSH_AUTH_SOCK=%t/keyring/ssh |
| | 80 | Restart=on-failure |
| | 81 | |
| | 82 | [Install] |
| | 83 | WantedBy=default.target |
| | 84 | |
| | 85 | This text is contained in this repository directory as `./config-shared/emacs/home/.config/systemd/user/emacs.service`. This file may be installed using the following command. |
| | 86 | |
| | 87 | $ cp ./config-shared/emacs/home/.config/systemd/user/emacs.service ~/.config/systemd/user/emacs.service |
| | 88 | |
| | 89 | Enable and start this service by running the following commands. |
| | 90 | |
| | 91 | systemctl enable --user emacs |
| | 92 | systemctl start --user emacs |
| | 93 | |
| | 94 | Successful running of this command should produce something like the following messages: |
| | 95 | |
| | 96 | Created symlink /home/baltakatei/.config/systemd/user/default.target.wants/emacs.service → /home/baltakatei/.config/systemd/user/emacs.service. |
| | 97 | |
| | 98 | A new process named `/usr/bin/emacs --daemon` should appear in `$ ps -aux | grep emacs` output. This process should appear automatically upon login. |
| | 99 | |
| | 100 | In order to use the daemon to edit a text file in the command line, the following command should be used. |
| | 101 | |
| | 102 | $ emacsclient -nw |
| | 103 | |
| | 104 | #### 2.3.b. Create `emacsclient` alias. |
| | 105 | |
| | 106 | Typing `emacsclient` instead of just `emacs` is inconvenient. Therefore, it's recommended to make an alias. |
| | 107 | |
| | 108 | ##### 2.3.b.i. `bash` alias |
| | 109 | |
| | 110 | If `bash` is your primary shell, then the alias can be included in the `~/.bash_aliases` file. The alias can be included by appending the `./config-shared/emacs/home/.bash_aliases.appendme` text file in this repository directory to the `~/.bash_aliases` file in the home directory. The following command may be used to to perform this append operation. |
| | 111 | |
| | 112 | $ cat ./config-shared/emacs/home/.bash_aliases.appendme >> ~/.bash_aliases |
| | 113 | |
| | 114 | The relevant portion of the `./config-shared/emacs/home/.bash_aliases.appendme` file is below. |
| | 115 | |
| | 116 | alias emacs='emacsclient -create-frame --alternate-editor=""' |
| | 117 | |
| | 118 | In order to see the alias changes, either logout and restart your shell or run `$ source ~/.bash_aliases`. |
| | 119 | |
| | 120 | ## 3. Conclusion. |
| | 121 | |
| | 122 | Emacs should now be configured to run automatically in the background as a daemon upon login. |
| | 123 | |
| | 124 | ## 4. References |
| | 125 | |
| | 126 | - <a name="melpa_2019_setupinst">1.</a> ["Getting started"][1]. https://melpa.org . Access date: 2020-04-17. [Archive link](https://web.archive.org/web/20200325114522/https://melpa.org/#/getting-started). Archive date: 2020-03-25. |
| | 127 | - <a name="se_20161221_emacsclimultieval">2.</a> ["emacs --eval of multiple functions on command line"][2]. Stack Exchange. Access date: 2020-04-17. [Archive link](https://web.archive.org/web/20200417002001/https://emacs.stackexchange.com/questions/29465/emacs-eval-of-multiple-functions-on-command-line/29467) |
| | 128 | - <a name="emacswiki_20200408_emacsdaemon">3.</a> ["Emacs As Daemon"][3]. EmacsWiki. Access date: 2020-04-17. License: GPLv2. [Archive link](https://web.archive.org/web/20200303223315/https://www.emacswiki.org/emacs/EmacsAsDaemon). Archive date: 2020-03-03. |
| | 129 | - <a name="emacswiki_20200325_emacsclient">4.</a> ["Emacs Client"][4]. EmacsWiki. Access date: 2020-04-17. License: GPLv2. [Archive link](https://web.archive.org/web/20190804144010/https://www.emacswiki.org/emacs/EmacsClient). Archive date: 2019-08-04. |
| | 130 | |
| | 131 | |
| | 132 | [1]: https://melpa.org/#/getting-started |
| | 133 | [2]: https://emacs.stackexchange.com/a/29467 |
| | 134 | [3]: https://www.emacswiki.org/emacs/EmacsAsDaemon |
| | 135 | [4]: https://www.emacswiki.org/emacs/EmacsClient |
| | 136 | [bktei_2020_homepage]: http://baltakatei.com |
| | 137 | [cc_20131125_bysa]: http://creativecommons.org/licenses/by-sa/4.0/ |
| | 138 | |
| | 139 | |
| | 140 | <hr> |
| | 141 | <p xmlns:dct="http://purl.org/dc/terms/" xmlns:cc="http://creativecommons.org/ns#">This work by <a rel="cc:attributionURL" href="http://baltakatei.com"><span rel="cc:attributionName">Steven Baltakatei Sandoval</span></a> is licensed under <a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=ccchooser" target="_blank" rel="license noopener noreferrer" style="display: inline-block;">CC BY-SA 4.0</a><a href="https://creativecommons.org/licenses/by-sa/4.0/?ref=ccchooser"><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc_icon.svg" /><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc-by_icon.svg" /><img style="height:22px!important;margin-left: 3px;vertical-align:text-bottom;opacity:0.7;" src="https://search.creativecommons.org/static/img/cc-sa_icon.svg" /></a></p> |
projects / BK-2020-03.git / blame_incremental