diff --git a/hosts/acernitro.el b/hosts/acernitro.el index 61f741f..f2a320e 100644 --- a/hosts/acernitro.el +++ b/hosts/acernitro.el @@ -1,3 +1,17 @@ +;; Acernitro +;; :PROPERTIES: +;; :header-args: :tangle hosts/acernitro.el +;; :END: + +;; The first machine with real hardware to deploy this configuration to. It's an Acer Nitro AN-515 with the NVIDIA / Intel hybrid graphics card. Due to the issues I encountered with this hardware setup, I again opted to install Ubuntu 20.04, and stripped away the components I don't need. + +;; + Set the browser manually +;; + Set the language to Canadian english +;; + Increase font size for high DPI screen + +;; Configure the browser. + + (setq dotfiles/browser "firefox" dotfiles/language "en_CA" dotfiles/font-size 132) diff --git a/hosts/localhost.el b/hosts/localhost.el index 38df7a3..2601e60 100644 --- a/hosts/localhost.el +++ b/hosts/localhost.el @@ -1 +1,11 @@ +;; Termux +;; :PROPERTIES: +;; :header-args: :tangle hosts/localhost.el +;; :END: + +;; Android devices do not use the Linux host names, so setting a custom hostname is pointless as it just changes the value of ~kernel.hostname~ and have no impact on the running system. It's recommended to leave the hostname as =localhost= in Termux. While this raises an issue with my host definition system, it's no more of an issue than the =rasberry= namespace. + +;; + Increase font size for small screen + + (setq dotfiles/font-size 132) diff --git a/hosts/raspberry.el b/hosts/raspberry.el index f03c37c..39265d1 100644 --- a/hosts/raspberry.el +++ b/hosts/raspberry.el @@ -1,3 +1,15 @@ +;; Raspberry +;; :PROPERTIES: +;; :header-args: :tangle hosts/raspberry.el +;; :END: + +;; Raspberry Pi 400 personal computer, and a small fleet of Zero, Zero WH, 4, and 4Bs. + +;; + Set the browser manually +;; + Set the language to Canadian english +;; + Increase font size for small screens + + (setq dotfiles/browser "chromium-browser" dotfiles/language "en_CA" dotfiles/font-size 132) diff --git a/hosts/virtualbox.el b/hosts/virtualbox.el index 2ac03fa..9c63a64 100644 --- a/hosts/virtualbox.el +++ b/hosts/virtualbox.el @@ -1,2 +1,13 @@ +;; Virtualbox +;; :PROPERTIES: +;; :header-args: :tangle hosts/virtualbox.el +;; :END: + +;; The first configuration, built using the Ubuntu 20.04 LTS server edition. + +;; + Set the browser manually +;; + Set the language to Canadian english + + (setq dotfiles/browser "firefox" dotfiles/language "en_CA") diff --git a/modules/core.el b/modules/core.el index 3ee9046..e2debaf 100644 --- a/modules/core.el +++ b/modules/core.el @@ -1,11 +1,38 @@ +;; Startup + +;; Emacs creates a lot of files relative to ~user-emacs-directory~, these files are not part of this immutable configuration and do not belong in the emacs directory. How can we solve this issue? Shortly after initialization, before most packages load, we change the value to ~dotfiles/cache~. I elaborate more on the technique in my post [[https://chrishayward.xyz/posts/immutable-emacs/][Immutable Emacs]]. + + (setq user-emacs-directory dotfiles/cache) + + +;; Because this project uses version-control, we can disable more unwanted features: +;; + Lock files +;; + Backup files + + (setq create-lockfiles nil make-backup-files nil) +;; Packages + +;; Download and install packages using [[https://github.com/raxod502/straight.el][straight.el]], a functional package manager that integrates with =use-package=, giving us more control over sourcing our packages. + +;; + Use the development branch +;; + Integrate with ~use-package~ + +;; Apply the configurations prior to bootstrapping the package manager, by setting (writing) to the variables that =straight= will ultimately read from. + + (setq straight-repository-branch "develop" straight-use-package-by-default t) + + +;; Bootstrap the package manager, downloading, installing, or configuring depending on the state of the configuration. All packages build from source, pinned to specific git commit hashes. + + (defvar bootstrap-version) (let ((bootstrap-file (expand-file-name "straight/repos/straight.el/bootstrap.el" user-emacs-directory)) @@ -19,10 +46,25 @@ (eval-print-last-sexp))) (load bootstrap-file nil 'nomessage)) + + +;; Complete the integration with ~use-package~ by installing it with =straight=. + + (straight-use-package 'use-package) +;; Cleanup + +;; Despite having our *stateful* and *immutable* configurations seperate, it's good practice to make efforts to reduce the trash created by Emacs. Install [[https://github.com/emacscollective/no-littering][no-littering]] to reduce the files created by Emacs. + + (use-package no-littering) + + +;; Emacs' default user interface is *horrendous*, let's do something about that. + + (setq inhibit-startup-message t initial-scratch-message "") @@ -35,9 +77,24 @@ (when (fboundp 'scroll-bar-mode) (scroll-bar-mode -1))) + + +;; Emacs has a long history of running on machines without gigabytes of available memory, let it realize its full potential! Just kidding, it just smashes *CPU0*. + + (setq gc-cons-treshold most-positive-fixnum gnutls-min-prime-bits 4096) +;; Babel + +;; *Organize your plain life in plain text* + +;; [[https://orgmode.org][Org-mode]] is one of the hallmark features of Emacs, and provides the basis for my Literate Programming platform. It's essentially a markdown language with rich features for project management, scheduling, development, and writing. It's hard to convey everything within its capabilities. + +;; + [[https://orgmode.org/worg/org-contrib/babel/languages/index.html][Babel languages]] +;; + [[https://orgmode.org/manual/Structure-Templates.html][Structure templates]] + + (use-package org :hook (org-mode . (lambda () (org-indent-mode) @@ -63,6 +120,11 @@ (org-babel-do-load-languages 'org-babel-load-languages '((shell . t) (emacs-lisp . t)))) + + +;; Build all of the =org= files within a given directory. + + (defun dotfiles/tangle (dir) "Recursively tangle the Org files within a directory." (let ((org-files (directory-files-recursively dir "org"))) diff --git a/modules/desktop.el b/modules/desktop.el index dd6f84b..a87747a 100644 --- a/modules/desktop.el +++ b/modules/desktop.el @@ -1,3 +1,13 @@ + + +;; Once the mail's synchronized, and has indexed with =mu=, it's time to install the required packages for Emacs. + +;; + Update every 5 minutes +;; + Scale text for all devices +;; + Sign outbound mail with GPG key +;; + Configure mail account(s) + + (use-package mu4e :load-path "/usr/share/emacs/site-lisp/mu4e" :custom (mu4e-maildir "~/.cache/mail") @@ -28,41 +38,104 @@ (smtpmail-smtp-service . 587) (smtpmail-stream-type . starttls)))))) + + +;; Use [[https://github.com/iqbalansari/mu4e-alert][mu4e-alert]] to give us desktop notifications about incoming mail. + + (use-package mu4e-alert :after mu4e :custom (mu4e-alert-set-default-style 'libnotify) :config (mu4e-alert-enable-notifications) (mu4e-alert-enable-mode-line-display)) + + +;; Create a keybinding to open the mail dashboard with =SPC m=. + + (dotfiles/leader "m" '(mu4e :which-key "Mail")) +;; Browser + +;; Write out the ~$BROWSER~ environment variable. + + (setenv "BROWSER" dotfiles/browser) +;; Methods + +;; Define a method to run an external process, allowing us to launch any application on a new process without interferring with Emacs. + + (defun dotfiles/run (command) "Run an external process." (interactive (list (read-shell-command "λ "))) (start-process-shell-command command nil command)) + + +;; Apply methods to the current call process to avoid issues with hooks. + + (defun dotfiles/run-in-background (command) (let ((command-parts (split-string command "[ ]+"))) (apply #'call-process `(,(car command-parts) nil 0 nil ,@(cdr command-parts))))) + + +;; Place keybindings for executing shell commands behind =SPC x=. + +;; + Run shell commands with =x= +;; + Run async shell commands with =z= + + (dotfiles/leader "x" '(:ignore t :which-key "Run") "xx" '(dotfiles/run :which-key "Run") "xz" '(async-shell-command :which-key "Async")) +;; Displays + +;; When the window manager first launches the ~init-hook~ executes, allowing us to define some custom logic. + +;; + Display time and date +;; + Display battery info (if available) + +;; In my personal configuration, I do not want the battery or time displayed within Emacs when it's not running as desktop environment because that information is typically already available. + + (defun dotfiles/init-hook () (exwm-workspace-switch-create 1) (setq display-time-and-date t) (display-battery-mode 1) (display-time-mode 1)) + + +;; Using =autorandr= with pre configured profiles, switching screens (AKA hot plugging) is also handled through a hook. + + (defun dotfiles/update-display () "Update the displays by forcing a change through autorandr." (dotfiles/run-in-background "autorandr --change --force")) +;; Configuration + +;; Connect our custom hooks and configure the input keys, a custom layer for key capture layers. + +;; + Enable =randr= support +;; + Pass through to Emacs +;; + =M-x= to Emacs +;; + =C-g= to Emacs +;; + =C-SPC= to Emacs +;; + Bindings with =S= (Super / Win) +;; + Reset =S-r= +;; + Launch =S-&= +;; + Workspace =S-[1..9]= + + (use-package exwm :custom (exwm-workspace-show-all-buffers t) (exwm-input-prefix-keys diff --git a/modules/editor.el b/modules/editor.el index 6692a41..81b0020 100644 --- a/modules/editor.el +++ b/modules/editor.el @@ -1,27 +1,62 @@ +;; Keys + +;; Make the =ESC= key quit (most) prompts, instead of the default =C-g=. + + (global-set-key (kbd "") 'keyboard-escape-quit) + + +;; Download [[https://github.com/justbur/emacs-which-key][which-key]], a package that displays the current incomplete keybinding input in a mini-buffer, showing available completion options. + + (use-package which-key :diminish which-key-mode :custom (which-key-idle-delay dotfiles/idle) :config (which-key-mode)) + + +;; Turn Emacs into Vim with [[https://evil.readthedocs.io/en/latest/index.html][evil-mode]], the extensible VI layer for Emacs. + + (use-package evil :custom (evil-want-integration t) ;; Required for `evil-collection'. (evil-want-keybinding nil) ;; Same as above :config (evil-mode 1)) + + +;; Unfortunately the default keybindings are *lacking*, but there is a community curated package [[https://github.com/emacs-evil/evil-collection][evil-collection]], which does a much better job implementing keybindings you would expect to find. + + (use-package evil-collection :after evil :config (evil-collection-init)) + + +;; Surround text with functions, quotations, and any other symbols using the [[https://github.com/emacs-evil/evil-surround][evil-surround]] package. + + (use-package evil-surround :after evil :config (global-evil-surround-mode 1)) + + +;; Toggle block comments using [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commentor]] and =M-;=. + + (use-package evil-nerd-commenter :after evil :bind ("M-;" . evilnc-comment-or-uncomment-lines)) + + +;; Implement the *leader* key using [[https://github.com/noctuid/general.el][general.el]], letting us easily configure prefixed keybindings in a much cleaner manner than the default methods. + + (use-package general :after evil :config @@ -31,48 +66,131 @@ :prefix dotfiles/leader-key :global-prefix dotfiles/leader-key-global)) + + +;; Use [[https://github.com/abo-abo/hydra][hydra]] for transient keybindings sharing a common prefix. + + (use-package hydra :defer t) +;; Help + +;; Use the built-in ~describe-*~ functionality of Emacs to quickly access documentation for packages, variables, and functions. Run helper functions with =SPC h=. + +;; + Packages =p= +;; + Variables =v= +;; + Functions =f= + + (dotfiles/leader "h" '(:ignore t :which-key "Help") "hp" '(describe-package :which-key "Package") "hv" '(describe-variable :which-key "Variable") "hf" '(describe-function :which-key "Function")) +;; Files + +;; For file navigation I use =dired=, included with Emacs by default. Dired feels more modern with prioritized icon fonts using [[https://github.com/domtronn/all-the-icons.el][all-the-icons]]. This makes navigation and visually parsing directories much faster, given that file types are quickly identified by their corresponding icons. + + (use-package all-the-icons) + + +;; Integration with =dired= comes from the [[https://github.com/jtbm37/all-the-icons-dired][all-the-icons-dired]] package. + + (use-package all-the-icons-dired :hook (dired-mode . all-the-icons-dired-mode)) + + +;; When opening =dired=, I don't want to have to press =RET= twice to navigate to the current directory. Avoid this with ~dired-jump~, included in the =dired-x= package shipped with =dired= and Emacs. + + (require 'dired-x) + + +;; By default =dired= will create a new buffer everytime you press =RET= over a directory. This leads to unwanted =dired= buffers needing closure. Avoid this behaviour with [[https://github.com/crocket/dired-single][dired-single]], reusing the same dired buffer. + +;; + Move up a directory with =h= +;; + Open a single buffer with =l= + + (use-package dired-single :config (evil-collection-define-key 'normal 'dired-mode-map "h" 'dired-single-up-directory "l" 'dired-single-buffer)) + + +;; Open a dired buffer with =SPC d=. + + (dotfiles/leader "d" '(dired-jump :which-key "Dired")) +;; Shell + +;; While not a traditional terminal emulator, =eshell= provides me with all of the functionality I expect and require from one. Some users may be wanting more, I would recommend they look into =vterm= included in the destkop module. Configure the infamous lambda prompt using [[https://github.com/zwild/eshell-prompt-extras][eshell-prompt-extras]] package. + + (use-package eshell-prompt-extras :custom (eshell-highlight-prompt nil) (eshell-prompt-function 'epe-theme-lambda)) + + +;; Open an =eshell= buffer with =SPC e=. + + (dotfiles/leader "e" '(eshell :which-key "Shell")) +;; Source + +;; #+ATTR_ORG: :width 420px +;; #+ATTR_HTML: :width 420px +;; #+ATTR_LATEX: :width 420px +;; [[./docs/images/2021-02-13-example-magit.gif]] + +;; Another hallmark feature is [[https://github.com/magit/magit][Magit]], a complete git porcelain within Emacs. + + (use-package magit :commands magit-status :custom (magit-display-buffer-function #'magit-display-buffer-same-window-except-diff-v1)) + + +;; Work directly with github issues / pull requests using [[https://github.com/magit/forge][Forge]]. + +;; + Requires a valid ~$GITHUB_TOKEN~ + + (use-package forge :after magit) + + +;; Open the *status* page for the current repository with =SPC g=. + + (dotfiles/leader "g" '(magit-status :which-key "Magit")) +;; Windows + +;; Window management with =SPC w=. +;; + Swap with =w= +;; + Close with =c= +;; + Motions with =h,j,k,l= +;; + Split with =s + = + + (dotfiles/leader "w" '(:ignore t :which-key "Window") "ww" '(window-swap-states :which-key "Swap") @@ -85,15 +203,36 @@ "wsj" '(split-window-below :which-key "Down") "wsl" '(split-window-right :which-key "Right")) +;; Shortcuts + +;; Implement shortcut bindings, cherry picked from Doom emacs. + +;; + Close buffers with =SPC c= +;; + Find files with =SPC . (period)= + + (dotfiles/leader "." '(find-file :which-key "Files") "c" '(kill-buffer-and-window :which-key "Close")) + + +;; Quit emacs with =SPC q=. +;; + Saving =q= +;; + Without =w= +;; + Frame (daemon) =f= + + (dotfiles/leader "q" '(:ignore t :which-key "Quit") "qq" '(save-buffers-kill-emacs :which-key "Save") "qw" '(kill-emacs :which-key "Now") "qf" '(delete-frame :which-key "Frame")) + + +;; Place runtime tweaks behind =SPC t=. + + (dotfiles/leader "t" '(:ignore t :which-key "Tweaks")) diff --git a/modules/interface.el b/modules/interface.el index d910c70..381bb0c 100644 --- a/modules/interface.el +++ b/modules/interface.el @@ -1,62 +1,183 @@ +;; Ivy + +;; Download and configure [[https://oremacs.com/swiper/][ivy]], a powerful selection menu for Emacs. + + (use-package ivy :diminish :config (ivy-mode 1)) + + +;; Counsel is a customized set of commands to replace built in completion buffers. + + (use-package counsel :after ivy :custom (counsel-linux-app-format-function #'counsel-linux-app-format-function-name-only) :config (counsel-mode 1)) + + +;; Switch buffers with =SPC , (comma)=. + + (dotfiles/leader "," '(counsel-switch-buffer :which-key "Buffers")) + + +;; Provide more information about each item with [[https://github.com/Yevgnen/ivy-rich][ivy-rich]]. + + (use-package ivy-rich :after counsel :init (ivy-rich-mode 1)) +;; Fonts + +;; Write out to all *3* of Emacs' default font faces. + + (set-face-attribute 'default nil :font dotfiles/font :height dotfiles/font-size) (set-face-attribute 'fixed-pitch nil :font dotfiles/font :height dotfiles/font-size) (set-face-attribute 'variable-pitch nil :font dotfiles/font :height dotfiles/font-size) + + +;; Define a transient keybinding for scaling the text. + + (defhydra hydra-text-scale (:timeout 4) "Scale" ("j" text-scale-increase "Increase") ("k" text-scale-decrease "Decrease") ("f" nil "Finished" :exit t)) + + +;; Increase the font size in buffers with =SPC t f=. +;; + Increase =j= +;; + Decrease =k= +;; + Finish =f= + + (dotfiles/leader "tf" '(hydra-text-scale/body :which-key "Font")) +;; Lines + +;; Relative line numbers are important when using =VI= emulation keys. You can prefix most commands with a *number*, allowing you to jump up / down by a line count. + +;; #+begin_example +;; 5: +;; 4: +;; 3: +;; 2: +;; 1: +;; 156: << CURRENT LINE >> +;; 1: +;; 2: +;; 3: +;; 4: +;; 5: +;; #+end_example + +;; https://github.com/emacsmirror/linum-relative +;; + Integrate with ~display-line-numbers-mode~ for performance + + (use-package linum-relative :custom (linum-relative-backend 'display-line-numbers-mode) :config (linum-relative-global-mode)) + + +;; Add line numbers to the toggles behind =SPC t l=. + + (dotfiles/leader "tl" '(linum-relative-global-mode :which-key "Lines")) + + +;; https://github.com/Fanael/rainbow-delimiters +;; + Colourize nested parenthesis + + (use-package rainbow-delimiters :hook (prog-mode . rainbow-delimiters-mode)) +;; Themes + +;; #+ATTR_ORG: :width 420px +;; #+ATTR_HTML: :width 420px +;; #+ATTR_LATEX: :width 420px +;; [[./docs/images/what-is-emacs-customizable.gif]] + +;; Cherry pick a few modules from =doom-emacs=. High quality and modern colour themes are provided in the [[https://github.com/hlissner/emacs-doom-themes][doom-themes]] package. + + (use-package doom-themes :init (load-theme 'doom-moonlight t)) + + +;; [[https://github.com/seagle0128/doom-modeline][doom-modeline]] provides an elegant status bar / modeline. + + (use-package doom-modeline :custom (doom-modeline-height 16) :config (doom-modeline-mode 1)) + + +;; Load a theme with =SPC t t=. + + (dotfiles/leader "tt" '(counsel-load-theme t t :which-key "Theme")) +;; Pretty + +;; Make programming buffers prettier with [[https://github.com/pretty-mode/pretty-mode][pretty-mode]], complimentary to the built in ~prettify-symbols-mode~. + + (use-package pretty-mode :hook (python-mode . turn-on-pretty-mode)) +;; Ligatures + +;; Enable font ligatures via [[https://github.com/jming422/fira-code-mode][fira-code-mode]], perform this action *only* when ~Fira Code~ is the current font. + + (when (display-graphic-p) (use-package fira-code-mode :hook (prog-mode org-mode))) + + +;; Toggle global ligature mode with =SPC t g=. + + (dotfiles/leader "tg" '(global-fira-code-mode :which-key "Ligatures")) +;; Dashboard + +;; #+ATTR_ORG: :width 420px +;; #+ATTR_HTML: :width 420px +;; #+ATTR_LATEX: :width 420px +;; [[./docs/images/desktop.png]] + +;; Present a dashboard when first launching Emacs. Customize the buttons of the navigator: + +;; + Brain @ http://localhost:8080 +;; + Homepage @ https://chrishayward.xyz +;; + Athabasca @ https://login.athabascau.ca/cas/login +;; + Bookshelf @ https://online.vitalsource.com + + (use-package dashboard :custom (dashboard-center-content t) (dashboard-set-init-info t) @@ -80,6 +201,11 @@ (lambda (&rest _) (browse-url "https://online.vitalsource.com")))))) :config (dashboard-setup-startup-hook)) + + +;; When running in *daemon* mode, ensure that the dashboard is the initial buffer. + + (setq initial-buffer-choice (lambda () (get-buffer "*dashboard*"))) diff --git a/modules/projects.el b/modules/projects.el index e7f1f24..c8aab34 100644 --- a/modules/projects.el +++ b/modules/projects.el @@ -1,25 +1,71 @@ +;; Projects +;; :PROPERTIES: +;; :header-args: :tangle modules/projects.el +;; :END: + +;; An IDE like experience (or better) can be achieved in Emacs using two *Microsoft* open source initiatives. + +;; + [[https://microsoft.github.io/language-server-protocol/][Language Server Protocol]] +;; + [[https://microsoft.github.io/debug-adapter-protocol/][Debug Adapter Protocol]] + +;; Add support for language servers with [[https://emacs-lsp.github.io/lsp-mode/][lsp-mode]]. + + (use-package lsp-mode :commands (lsp lsp-deferred) :custom (lsp-idle-delay (* 5 dotfiles/idle))) + + +;; [[https://emacs-lsp.github.io/lsp-ui/][lsp-ui]] provides UI improvements for =lsp-mode=. + + (use-package lsp-ui :after lsp :custom (lsp-ui-doc-position 'at-point) (lsp-ui-doc-delay 0.500)) + + +;; [[https://emacs-lsp.github.io/dap-mode/][Dap-mode]] adds support for the debug adapter protocol to Emacs. + + (use-package dap-mode :commands (dap-debug)) +;; Containers + +;; Use ~docker~ for running containers. Download and install https://github.com/Silex/docker.el, allowing us to manage containers within Emacs. + + (use-package docker :commands (docker)) + + +;; Open the management screen with =SPC k=. + + (dotfiles/leader "k" '(docker :which-key "Docker")) +;; Management + +;; Configure [[https://projectile.mx][projectile]], a project interaction library for Emacs. It provides a nice set of features for operating on a project level without introducing external dependencies. + + (use-package projectile :custom (projectile-project-search-path '("~/.local/source")) :config (projectile-mode)) +;; Completion + +;; Text completion framework via =company= aka *Complete Anything*. + +;; http://company-mode.github.io/ +;; + Integrate with =lsp-mode= + + (use-package company :after lsp) @@ -27,37 +73,99 @@ :after (lsp company) :custom (company-backend 'company-lsp)) +;; Passwords + +;; Pass makes managing passwords extremely easy, encrypring them in a file structure and providing easy commands for generating, modify, and copying passwords. =password-store.el= provides a wrapper for the functionality within Emacs. + + (use-package password-store :custom (password-store-dir dotfiles/passwords)) + + +;; Configure keybindings behind =SPC p=. +;; + Copy with =p= +;; + Rename with =r= +;; + Generate with =g= + + (dotfiles/leader "p" '(:ignore t :which-key "Passwords") "pp" '(password-store-copy :which-key "Copy") "pr" '(password-store-rename :which-key "Rename") "pg" '(password-store-generate :which-key "Generate")) + + +;; Set the ~GOPATH~ environment variable prior to loading, this allows us to change the default value of ~$HOME/go~ to ~$HOME/.go~. + + (setenv "GOPATH" (concat (getenv "HOME") "/.go/")) + + +;; Additionally, include the =bin= subdirectory of the ~$GOPATH~ in the ~$PATH~ variable, adding compiled golang programs. + + (setenv "PATH" (concat (getenv "GOPATH") "bin:" (getenv "PATH"))) + + +;; Finally we can include the =go-mode= package, integrating it with =lsp=. + + (use-package go-mode :hook (go-mode . lsp) :custom (lsp-go-gopls-server-path "~/.go/bin/gopls")) + + +;; Apply some custom behaviour before saving: + +;; + Format buffer +;; + Organize imports + + (defun dotfiles/go-hook () (add-hook 'before-save-hook #'lsp-format-buffer t t) (add-hook 'before-save-hook #'lsp-organize-imports t t)) (add-hook 'go-mode-hook #'dotfiles/go-hook) + + +;; Add a golang source code block structure template with ~