From: Steven Baltakatei Sandoval Date: Fri, 17 Apr 2020 02:52:05 +0000 (+0000) Subject: Created and added emacs config instructions and files. X-Git-Tag: 0.1.0~26 X-Git-Url: https://zdv2.bktei.com/gitweb/BK-2020-03.git/commitdiff_plain/1556783e58f2c06d95012cff362b91ff26a600e9 Created and added emacs config instructions and files. --- diff --git a/config-shared/emacs/INSTRUCTIONS.md b/config-shared/emacs/INSTRUCTIONS.md new file mode 100644 index 0000000..1601289 --- /dev/null +++ b/config-shared/emacs/INSTRUCTIONS.md @@ -0,0 +1,138 @@ + + + +# Setup Instructions for `emacs` + +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:42Z. + +## 1. Summary + +Emacs is a command line editor. This document contains instructions and files required to install and customize Emacs on GNU/Linux Debian 10 machines. + +### 1.1. File list + + ./config-shared/emacs/home/.emacs.d/init.el # enables MELPA repository + ./config-shared/emacs/home/.config/systemd/user/emacs.service # required for automatic daemon startup + ./config-shared/emacs/home/.bash_aliases.appendme # contains alias for use with emacs daemon + +## 2. Instructions + +### 2.1. Install `emacs` package + +#### 2.1.a. Typical Debian install + +Use `$ sudo apt-get install emacs` to install `emacs`. + +#### 2.1.b. Headless Debian install (no GUI) + +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`. + +### 2.2. Enable MELPA package repository + +MELPA is a package repository for packages that add functionality to `emacs`. Detailed instructions for installing it may be found at melpa.org.[[1]](#melpa_2019_setupinst) + +#### 2.2.a. Typical install + +Create and/or edit the `~/.emacs.d/init.el` file to include the following text elisp code: + + (require 'package) + (let* ((no-ssl (and (memq system-type '(windows-nt ms-dos)) + (not (gnutls-available-p)))) + (proto (if no-ssl "http" "https"))) + (when no-ssl (warn "\ + Your version of Emacs does not support SSL connections, + which is unsafe because it allows man-in-the-middle attacks. + There are two things you can do about this warning: + 1. Install an Emacs version that does support SSL and be safe. + 2. Remove this warning from your init file so you won't see it again.")) + (add-to-list 'package-archives (cons "melpa" (concat proto "://melpa.org/packages/")) t) + ;; Comment/uncomment this line to enable MELPA Stable if desired. See `package-archive-priorities` + ;; and `package-pinned-packages`. Most users will not need or want to do this. + ;;(add-to-list 'package-archives (cons "melpa-stable" (concat proto "://stable.melpa.org/packages/")) t) + ) + (package-initialize) + +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. + + $ mkdir ~/.emacs.d + $ cp ./config-shared/emacs/home/.emacs.d/init.el ~/.emacs.d/init.el + +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.[[2]](#se_20161221_emacsclimultieval) + +### 2.3. Configure `emacs` daemon and `emacsclient` + +A convenient way to share buffers between different shells (ex: across guake and Terminal) is to edit files using multiple instances of `emacsclient`[[4]](#emacswiki_20200325_emacsclient) which each communicate with a single instance of `emacs --daemon`[[3]](#emacswiki_20200408_emacsdaemon). 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`). + +#### 2.3.a. Create `emacs` daemon as a user service. + +Create the `~/.config/systemd/user/emacs.service` file to be the following text: + + [Unit] + Description=Emacs text editor + Documentation=info:emacs man:emacs(1) https://gnu.org/software/emacs/ + + [Service] + Type=forking + ExecStart=/usr/bin/emacs --daemon + ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)" + Encopy itvironment=SSH_AUTH_SOCK=%t/keyring/ssh + Restart=on-failure + + [Install] + WantedBy=default.target + +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. + + $ cp ./config-shared/emacs/home/.config/systemd/user/emacs.service ~/.config/systemd/user/emacs.service + +Enable and start this service by running the following commands. + + systemctl enable --user emacs + systemctl start --user emacs + +Successful running of this command should produce something like the following messages: + + Created symlink /home/baltakatei/.config/systemd/user/default.target.wants/emacs.service → /home/baltakatei/.config/systemd/user/emacs.service. + +A new process named `/usr/bin/emacs --daemon` should appear in `$ ps -aux | grep emacs` output. This process should appear automatically upon login. + +In order to use the daemon to edit a text file in the command line, the following command should be used. + + $ emacsclient -nw + +#### 2.3.b. Create `emacsclient` alias. + +Typing `emacsclient` instead of just `emacs` is inconvenient. Therefore, it's recommended to make an alias. + +##### 2.3.b.i. `bash` alias + +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. + + $ cat ./config-shared/emacs/home/.bash_aliases.appendme >> ~/.bash_aliases + +The relevant portion of the `./config-shared/emacs/home/.bash_aliases.appendme` file is below. + + alias emacs='emacsclient -create-frame --alternate-editor=""' + +## 3. Conclusion. + +Emacs should now be configured to run automatically in the background as a daemon upon login. + +## 4. References + +- 1. ["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. +- 2. ["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) +- 3. ["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. +- 4. ["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. + + +[1]: https://melpa.org/#/getting-started +[2]: https://emacs.stackexchange.com/a/29467 +[3]: https://www.emacswiki.org/emacs/EmacsAsDaemon +[4]: https://www.emacswiki.org/emacs/EmacsClient +[bktei_2020_homepage]: http://baltakatei.com +[cc_20131125_bysa]: http://creativecommons.org/licenses/by-sa/4.0/ + + +
+

This work by Steven Baltakatei Sandoval is licensed under CC BY-SA 4.0

diff --git a/config-shared/emacs/home/.bash_aliases.appendme b/config-shared/emacs/home/.bash_aliases.appendme new file mode 100644 index 0000000..d8e12b0 --- /dev/null +++ b/config-shared/emacs/home/.bash_aliases.appendme @@ -0,0 +1 @@ +alias emacs='emacsclient -create-frame --alternate-editor=""' # Note: This alias requires `emacs --daemon` to work properly. See https://www.emacswiki.org/emacs/EmacsAsDaemon . diff --git a/config-shared/emacs/home/.config/systemd/user/emacs.service b/config-shared/emacs/home/.config/systemd/user/emacs.service new file mode 100644 index 0000000..f3d7df9 --- /dev/null +++ b/config-shared/emacs/home/.config/systemd/user/emacs.service @@ -0,0 +1,13 @@ +[Unit] +Description=Emacs text editor +Documentation=info:emacs man:emacs(1) https://gnu.org/software/emacs/ + +[Service] +Type=simple +ExecStart=/usr/bin/emacs --fg-daemon +ExecStop=/usr/bin/emacsclient --eval "(kill-emacs)" +Environment=SSH_AUTH_SOCK=%t/keyring/ssh +Restart=on-failure + +[Install] +WantedBy=default.target diff --git a/log.txt b/log.txt index d05e036..c9598ad 100644 --- a/log.txt +++ b/log.txt @@ -15,3 +15,12 @@ executable binaries respectively. Each should be added to PATH on all of my Debian GNU/Linux machines. :: :: :: :: + +2020-04-17T02:47Z; baltakatei> + +Renamed repository directory from `baltakatei_exec_testing` to +`baltakatei_exec_dev`. + +Created setup instructions and staged configuration files for `emacs`. + +:: :: :: ::