core: minor refactors and comment revisions

core/autoload/themes.el

@@ -1,5 +1,13 @@
 ;;; core/autoload/themes.el -*- lexical-binding: t; -*-
 
+;;;###autoload
+(defconst doom-customize-theme-hook nil)
+
+(add-hook! 'doom-load-theme-hook
+  (defun doom-apply-customized-faces-h ()
+    "Run `doom-customize-theme-hook'."
+    (run-hooks 'doom-customize-theme-hook)))
+
 (defun doom--custom-theme-set-face (spec)
   (cond ((listp (car spec))
          (cl-loop for face in (car spec)
@@ -9,13 +17,6 @@
          `((,(car spec) ((t ,(cdr spec))))))
         (`((,(car spec) ,(cdr spec))))))
 
-;;;###autoload
-(defconst doom-customize-theme-hook nil)
-
-(add-hook! 'doom-load-theme-hook
-  (defun doom-apply-customized-faces-h ()
-    (run-hooks 'doom-customize-theme-hook)))
-
 ;;;###autoload
 (defmacro custom-theme-set-faces! (theme &rest specs)
   "Apply a list of face SPECS as user customizations for THEME.

core/autoload/ui.el

@@ -48,7 +48,7 @@ are open."
 In interactive Emacs, this just inhibits messages from appearing in the
 minibuffer. They are still logged to *Messages*.
 
-In tty Emacs, messages suppressed completely."
+In tty Emacs, messages are suppressed completely."
   (quiet! (apply orig-fn args)))
 
 

core/cli/install.el

@@ -95,5 +95,5 @@ name. e.g.
 
     (print! (success "\nFinished! Doom is ready to go!\n"))
     (with-temp-buffer
-      (insert-file-contents (doom-glob doom-core-dir "templates/QUICKSTART_INTRO"))
+      (insert-file-contents (doom-path doom-core-dir "templates/QUICKSTART_INTRO"))
       (print! "%s" (buffer-string)))))

core/core-editor.el

@@ -330,8 +330,7 @@ or file path may exist now."
   ;; persist variables across sessions
   :defer-incrementally custom
   :hook (doom-first-input . savehist-mode)
-  :init
-  (setq savehist-file (concat doom-cache-dir "savehist"))
+  :custom (savehist-file (concat doom-cache-dir "savehist"))
   :config
   (setq savehist-save-minibuffer-history t
         savehist-autosave-interval nil     ; save on kill only
@@ -342,7 +341,7 @@ or file path may exist now."
           search-ring regexp-search-ring)) ; persist searches
   (add-hook! 'savehist-save-hook
     (defun doom-savehist-unpropertize-variables-h ()
-      "Remove text properties from `kill-ring' for a smaller savehist file."
+      "Remove text properties from `kill-ring' to reduce savehist cache size."
       (setq kill-ring
             (mapcar #'substring-no-properties
                     (cl-remove-if-not #'stringp kill-ring))
@@ -365,9 +364,7 @@ the unwritable tidbits."
 (use-package! saveplace
   ;; persistent point location in buffers
   :hook (doom-first-file . save-place-mode)
-  :init
-  (setq save-place-file (concat doom-cache-dir "saveplace")
-        save-place-limit 100)
+  :custom (save-place-file (concat doom-cache-dir "saveplace"))
   :config
   (defadvice! doom--recenter-on-load-saveplace-a (&rest _)
     "Recenter on cursor when loading a saved place."
@@ -382,20 +379,20 @@ the unwritable tidbits."
   (defadvice! doom--dont-prettify-saveplace-cache-a (orig-fn)
     "`save-place-alist-to-file' uses `pp' to prettify the contents of its cache.
 `pp' can be expensive for longer lists, and there's no reason to prettify cache
-files, so we replace calls to `pp' with the much faster `prin1'."
+files, so this replace calls to `pp' with the much faster `prin1'."
     :around #'save-place-alist-to-file
     (letf! ((#'pp #'prin1)) (funcall orig-fn))))
 
 
 (use-package! server
   :when (display-graphic-p)
-  :after-call pre-command-hook after-find-file focus-out-hook
+  :after-call doom-first-input-hook doom-first-file-hook focus-out-hook
+  :custom (server-auth-dir (concat doom-emacs-dir "server/"))
   :defer 1
   :init
   (when-let (name (getenv "EMACS_SERVER_NAME"))
     (setq server-name name))
   :config
-  (setq server-auth-dir (concat doom-emacs-dir "server/"))
   (unless (server-running-p)
     (server-start)))
 

core/core-modules.el

@@ -117,12 +117,13 @@ non-nil."
     (when-let (init-p (load! doom-module-init-file doom-private-dir t))
       (doom-log "Initializing user config")
       (maphash (doom-module-loader doom-module-init-file) doom-modules)
-      (run-hook-wrapped 'doom-before-init-modules-hook #'doom-run-hook)
+      (doom-run-hooks 'doom-before-init-modules-hook)
       (unless no-config-p
         (maphash (doom-module-loader doom-module-config-file) doom-modules)
-        (run-hook-wrapped 'doom-init-modules-hook #'doom-run-hook)
+        (doom-run-hooks 'doom-init-modules-hook)
         (load! "config" doom-private-dir t)
-        (load custom-file 'noerror (not doom-debug-mode))))))
+        (when custom-file
+          (load custom-file 'noerror (not doom-debug-mode)))))))
 
 
 ;;
@@ -315,8 +316,7 @@ those directories. The first returned path is always `doom-private-dir'."
   "Minimally initialize `doom-modules' (a hash table) and return it.
 This value is cached. If REFRESH-P, then don't use the cached value."
   (if all-p
-      (cl-loop for path in (cdr (doom-module-load-path 'all))
-               collect (doom-module-from-path path))
+      (mapcar #'doom-module-from-path (cdr (doom-module-load-path 'all)))
     doom-modules))
 
 

core/core-packages.el

@@ -361,6 +361,8 @@ installed."
                                  plist :modules
                                  (list (doom-module-from-path file))))
                           doom-packages))))))))
+    (user-error
+     (user-error (error-message-string e)))
     (error
      (signal 'doom-package-error
              (list (doom-module-from-path file)

core/core-ui.el

@@ -162,8 +162,12 @@ or if the current buffer is read-only or not file-visiting."
 ;;
 ;;; General UX
 
-;; Simpler confirmation prompt when killing Emacs
+;; A simple confirmation prompt when killing Emacs. But only prompt when there
+;; are real buffers open.
 (setq confirm-kill-emacs #'doom-quit-p)
+;; Prompt for confirmation when deleting a non-empty frame; a last line of
+;; defense against accidental loss of work.
+(global-set-key [remap delete-frame] #'doom/delete-frame-with-prompt)
 
 ;; Don't prompt for confirmation when we create a new file or buffer (assume the
 ;; user knows what they're doing).
@@ -292,12 +296,16 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original
 (setq frame-resize-pixelwise t)
 
 ;; But do not resize windows pixelwise, this can cause crashes in some cases
-;; where we resize windows too quickly.
+;; when resizing too many windows at once or rapidly.
 (setq window-resize-pixelwise nil)
 
 ;; Disable tool, menu, and scrollbars. Doom is designed to be keyboard-centric,
 ;; so these are just clutter (the scrollbar also impacts performance). Whats
 ;; more, the menu bar exposes functionality that Doom doesn't endorse.
+;;
+;; I am intentionally avoid using `menu-bar-mode', `tool-bar-mode', and
+;; `scroll-bar-mode' because they do extra and unnecessary work that can be more
+;; concisely, and efficiently, expressed with these six lines:
 (push '(menu-bar-lines . 0)   default-frame-alist)
 (push '(tool-bar-lines . 0)   default-frame-alist)
 (push '(vertical-scroll-bars) default-frame-alist)
@@ -316,21 +324,18 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original
       window-divider-default-right-width 1)
 (add-hook 'doom-init-ui-hook #'window-divider-mode)
 
-;; Prompt for confirmation when deleting a non-empty frame; a last line of
-;; defense against accidental loss of work.
-(global-set-key [remap delete-frame] #'doom/delete-frame-with-prompt)
-
-;; always avoid GUI
+;; GUIs are inconsistent across systems and themes (and will rarely match our
+;; active Emacs theme). They impose inconsistent shortcut key paradigms too.
+;; It's best to avoid GUIs altogether and have Emacs handle the prompting, since
+;; its promtps are governed by the same rules and keybinds as the rest of Emacs.
 (setq use-dialog-box nil)
-;; Don't display floating tooltips; display their contents in the echo-area,
-;; because native tooltips are ugly.
 (when (bound-and-true-p tooltip-mode)
   (tooltip-mode -1))
-;; ...especially on linux
 (when IS-LINUX
   (setq x-gtk-use-system-tooltips nil))
 
- ;; Favor vertical splits over horizontal ones. Screens are usually wide.
+ ;; Favor vertical splits over horizontal ones. Monitors are trending toward
+ ;; wide, rather than tall.
 (setq split-width-threshold 160
       split-height-threshold nil)
 
@@ -353,8 +358,7 @@ windows, switch to `doom-fallback-buffer'. Otherwise, delegate to original
 ;; Typing yes/no is obnoxious when y/n will do
 (fset #'yes-or-no-p #'y-or-n-p)
 
-;; Try really hard to keep the cursor from getting stuck in the read-only prompt
-;; portion of the minibuffer.
+;; Try to keep the cursor out of the read-only portions of the minibuffer.
 (setq minibuffer-prompt-properties '(read-only t intangible t cursor-intangible t face minibuffer-prompt))
 (add-hook 'minibuffer-setup-hook #'cursor-intangible-mode)
 
@@ -726,8 +730,9 @@ This offers a moderate boost in startup (or theme switch) time, so long as
   (put sym 'disabled "Doom doesn't support `customize', configure Emacs from $DOOMDIR/config.el instead"))
 (put 'customize-themes 'disabled "Set `doom-theme' or use `load-theme' in $DOOMDIR/config.el instead")
 
-;; Doesn't exist in terminal Emacs, so we define it to prevent void-function
-;; errors emitted from packages that blindly try to use it.
+;; Doesn't exist in terminal Emacs, but some Emacs packages (internal and
+;; external) use it anyway, leading to a void-function error, so define a no-op
+;; substitute to suppress them.
 (unless (fboundp 'define-fringe-bitmap)
   (fset 'define-fringe-bitmap #'ignore))
 

core/core.el

@@ -434,7 +434,8 @@ intervals."
   (if (not now)
       (appendq! doom-incremental-packages packages)
     (while packages
-      (let ((req (pop packages)))
+      (let* ((gc-cons-threshold most-positive-fixnum)
+             (req (pop packages)))
         (unless (featurep req)
           (doom-log "Incrementally loading %s" req)
           (condition-case-unless-debug e
@@ -443,12 +444,11 @@ intervals."
                     ;; or is unreadable, Emacs throws up file-missing errors, so
                     ;; we set it to a directory we know exists and is readable.
                     (let ((default-directory doom-emacs-dir)
-                          (gc-cons-threshold most-positive-fixnum)
                           file-name-handler-alist)
                       (require req nil t))
                     t)
                   (push req packages))
-            ((error debug)
+            (error
              (message "Failed to load %S package incrementally, because: %s"
                       req e)))
           (if (not packages)
@@ -473,6 +473,11 @@ If this is a daemon session, load them all immediately instead."
 ;;
 ;;; Bootstrap helpers
 
+(defun doom-finish-init-h ()
+  "Set `doom-init-time'."
+  (setq doom-init-time
+        (float-time (time-subtract (current-time) before-init-time))))
+
 (defun doom-display-benchmark-h (&optional return-p)
   "Display a benchmark including number of packages and modules loaded.
 
@@ -481,9 +486,7 @@ If RETURN-P, return the message as a string instead of displaying it."
            "Doom loaded %d packages across %d modules in %.03fs"
            (- (length load-path) (length (get 'load-path 'initial-value)))
            (if doom-modules (hash-table-count doom-modules) 0)
-           (or doom-init-time
-               (setq doom-init-time
-                     (float-time (time-subtract (current-time) before-init-time))))))
+           (or doom-init-time (doom-finish-init-h))))
 
 (defun doom-load-envvars-file (file &optional noerror)
   "Read and set envvars from FILE.
@@ -607,12 +610,11 @@ to least)."
     ;; like `doom-modules', `doom-disabled-packages', `load-path',
     ;; `auto-mode-alist', and `Info-directory-list'. etc. Compiling them into
     ;; one place is a big reduction in startup time.
-    (condition-case e
+    (condition-case-unless-debug e
         ;; Avoid `file-name-sans-extension' for premature optimization reasons.
         ;; `string-remove-suffix' is cheaper because it performs no file sanity
         ;; checks; just plain ol' string manipulation.
-        (load (string-remove-suffix ".el" doom-autoloads-file)
-              nil 'nomessage)
+        (load (string-remove-suffix ".el" doom-autoloads-file) nil 'nomessage)
       (file-missing
        ;; If the autoloads file fails to load then the user forgot to sync, or
        ;; aborted a doom command midway!
@@ -624,6 +626,8 @@ to least)."
                  (list "Doom is in an incomplete state"
                        "run 'doom sync' on the command line to repair it")))))
 
+    (if doom-debug-p (doom-debug-mode +1))
+
     ;; Load shell environment, optionally generated from 'doom env'. No need
     ;; to do so if we're in terminal Emacs, where Emacs correctly inherits
     ;; your shell environment.
@@ -642,20 +646,16 @@ to least)."
     (eval-after-load 'package '(require 'core-packages))
     (eval-after-load 'straight '(doom-initialize-packages))
 
-    ;; Bootstrap our GC manager
-    (add-hook 'doom-first-buffer-hook #'gcmh-mode)
-
     ;; Bootstrap the interactive session
     (add-hook 'after-change-major-mode-hook #'doom-run-local-var-hooks-h)
     (add-hook 'emacs-startup-hook #'doom-load-packages-incrementally-h)
     (add-hook 'window-setup-hook #'doom-display-benchmark-h)
     (doom-run-hook-on 'doom-first-buffer-hook '(find-file-hook doom-switch-buffer-hook))
     (doom-run-hook-on 'doom-first-file-hook   '(find-file-hook dired-initial-position-hook))
     (doom-run-hook-on 'doom-first-input-hook  '(pre-command-hook))
-    (if doom-debug-p (doom-debug-mode +1))
 
-    ;; Load core/core-*.el, the user's private init.el, then their config.el
-    (doom-initialize-modules force-p))
+    ;; Bootstrap our GC manager
+    (add-hook 'doom-first-buffer-hook #'gcmh-mode))
 
   doom-init-p)
 

early-init.el

@@ -8,6 +8,11 @@
 ;; enabling `gcmh-mode'. Not resetting it will cause stuttering/freezes.
 (setq gc-cons-threshold most-positive-fixnum)
 
+;; Prevent unwanted runtime compilation for gccemacs (native-comp) users;
+;; packages are compiled ahead-of-time when they are installed and site files
+;; are compiled when gccemacs is installed.
+(setq comp-deferred-compilation nil)
+
 ;; In noninteractive sessions, prioritize non-byte-compiled source files to
 ;; prevent the use of stale byte-code. Otherwise, it saves us a little IO time
 ;; to skip the mtime checks on every *.elc file.
@@ -35,7 +40,7 @@
             ;; `file-name-handler-alist' since startup we want to preserve.
             (delete-dups (append file-name-handler-alist
                                  old-file-name-handler-alist))))
-    (add-hook 'emacs-startup-hook #'doom-reset-file-handler-alist-h)))
+    (add-hook 'window-setup-hook #'doom-reset-file-handler-alist-h 101)))
 
 ;; Ensure Doom is running out of this file's directory
 (setq user-emacs-directory (file-name-directory load-file-name))

init.el

@@ -33,5 +33,25 @@
   (load (concat (file-name-directory load-file-name) "early-init")
         nil t))
 
-;; And let 'er rip!
+;; Ensure Doom's core libraries are properly initialized, autoloads file is
+;; loaded, and hooks set up for an interactive session.
 (doom-initialize)
+
+;; Now we load all enabled modules in the order dictated by your `doom!' block
+;; in $DOOMDIR/init.el. `doom-initialize-modules' loads them (and hooks) in the
+;; given order:
+;;
+;;   $DOOMDIR/init.el
+;;   {$DOOMDIR,~/.emacs.d}/modules/*/*/init.el
+;;   `doom-before-init-modules-hook'
+;;   {$DOOMDIR,~/.emacs.d}/modules/*/*/config.el
+;;   `doom-init-modules-hook'
+;;   $DOOMDIR/config.el
+;;   `doom-after-init-modules-hook'
+;;   `after-init-hook'
+;;   `emacs-startup-hook'
+;;   `doom-init-ui-hook'
+;;   `window-setup-hook'
+;;
+;; And then we're good to go!
+(doom-initialize-modules)