From e3bc367ba2f6571f2cfa47e6ba23fc92dd4d0961 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Sat, 7 Dec 2024 14:25:27 -0500 Subject: [PATCH] nit: minor comment revision --- early-init.el | 41 +++++++++++++++++---------------- lisp/doom.el | 63 +++++++++++++++++++++++++-------------------------- 2 files changed, 53 insertions(+), 51 deletions(-) diff --git a/early-init.el b/early-init.el index d40c5e907..0e76bc4ad 100644 --- a/early-init.el +++ b/early-init.el @@ -27,26 +27,28 @@ ;;; Code: (let (file-name-handler-alist) - ;; PERF: Garbage collection is a big contributor to startup times. This fends - ;; it off, but will be reset later by `gcmh-mode'. Not resetting it later - ;; causes stuttering/freezes. - (if noninteractive - ;; PERF: Deferring the GC in non-interactive sessions isn't as important, - ;; but still yields a notable benefit. Still, avoid setting it to high - ;; here, as runaway memory usage is a real risk in longer sessions. + ;; PERF: Garbage collection is a big contributor to startup times in both + ;; interactive and CLI sessions, so I defer it. + (if noninteractive ; in CLI sessions + ;; PERF: GC deferral is less important in the CLI, but still helps script + ;; startup times. Just don't set it too high to avoid runaway memory + ;; usage in long-running elisp shell scripts. (setq gc-cons-threshold 134217728 ; 128mb ;; Backported from 29 (see emacs-mirror/emacs@73a384a98698) gc-cons-percentage 1.0) + ;; PERF: Doom relies on `gcmh-mode' to reset this while the user is idle, so + ;; I effectively disable GC during startup. DON'T COPY THIS BLINDLY! If + ;; it's not reset later there will be stuttering, freezes, and crashes. (setq gc-cons-threshold most-positive-fixnum)) - ;; PERF: Don't use precious startup time checking mtime on elisp bytecode. - ;; Ensuring correctness is 'doom sync's job, not the interactive session's. - ;; Still, stale byte-code will cause *heavy* losses in startup efficiency, - ;; but performance is unimportant when Emacs is in an error state. + ;; PERF: Don't use precious startup time to check mtimes on elisp bytecode. + ;; Ensuring correctness is 'doom sync's job. Although stale byte-code will + ;; heavily impact startup times, performance is unimportant when Emacs is in + ;; an error state. (setq load-prefer-newer noninteractive) ;; UX: Respect DEBUG envvar as an alternative to --debug-init, and to make - ;; startup sufficiently verbose from this point on. + ;; startup more verbose sooner. (when (getenv-internal "DEBUG") (setq init-file-debug t debug-on-error t)) @@ -76,10 +78,10 @@ (setq user-emacs-directory (expand-file-name init-dir)))) ;; FIX: Discard the switch to prevent "invalid option" errors later. (push (cons "--profile" (lambda (_) (pop argv))) command-switch-alist) - ;; Running 'doom sync' or 'doom profile sync' (re)generates a light - ;; profile loader in $EMACSDIR/profiles/load.el (or $DOOMPROFILELOADFILE), - ;; after reading `doom-profile-load-path'. This loader requires - ;; `$DOOMPROFILE' be set to function. + ;; Running 'doom sync' or 'doom profile sync --all' (re)generates a light + ;; profile loader in $XDG_DATA_HOME/doom/profiles.X.el (or + ;; $DOOMPROFILELOADFILE), after reading `doom-profile-load-path'. This + ;; loader requires `$DOOMPROFILE' be set to function. (setenv "DOOMPROFILE" profile) (or (load (let ((windows? (memq system-type '(ms-dos windows-nt cygwin)))) (expand-file-name @@ -133,9 +135,10 @@ ;; fit guess. It's better than Emacs' 80kb default. (setq gc-cons-threshold (* 16 1024 1024)) nil)) - ;; In non-interactive sessions, leave to the consumer to call - ;; `doom-initialize' at the best time, otherwise we need to initialize - ;; ASAP for the Emacs session ahead. + ;; Sets up Doom (particularly `doom-profile') for the session ahead. This + ;; loads the profile's init file, if it's available. In interactive + ;; session, a missing profile is an error state, in a non-interactive one, + ;; it's not (and left to the consumer to deal with). (doom-initialize (not noninteractive)) ;; If we're here, the user wants to load another config/profile (that may or ;; may not be a Doom config). diff --git a/lisp/doom.el b/lisp/doom.el index 38a5bed30..e4cc0ce47 100644 --- a/lisp/doom.el +++ b/lisp/doom.el @@ -70,13 +70,14 @@ ;; ;;; Code: -;; For `when-let*' and `if-let*' on versions of Emacs before they were autoloaded. +;; For the `when-let*' and `if-let*' macros on older versions of Emacs, before +;; they were autoloaded. (eval-when-compile (require 'subr-x)) -(eval-and-compile ; Check version at both compile and runtime. - ;; Doom's minimum supported version of Emacs is 27.1. Its my goal to support - ;; one major version below the stable release, for about a year or until - ;; stable is ubiquitous (or at least easily accessible) across Linux distros. +(eval-and-compile + ;; Doom core supports Emacs 27.1 and newer. However, keep in mind that modules + ;; may have different requirements (e.g. the official module library requires + ;; 29.x or newer). (when (< emacs-major-version 27) (user-error (concat @@ -116,8 +117,7 @@ ;;; Custom features & global constants ;; Doom has its own features that its modules, CLI, and user extensions can ;; announce, and don't belong in `features', so they are stored here, which can -;; include information about the external system environment. Module-specific -;; features are kept elsewhere, however. +;; include information about the external system environment. (defconst doom-system (pcase system-type ('darwin '(macos bsd)) @@ -133,8 +133,7 @@ (defconst doom--system-linux-p (eq 'linux (car doom-system))) ;; `system-type' is esoteric, so I create a pseudo feature as a stable and -;; consistent alternative, and all while using the same `featurep' interface -;; we're already familiar with. +;; consistent alternative, for use with `featurep'. (push :system features) (put :system 'subfeatures doom-system) @@ -151,13 +150,13 @@ ;; The `native-compile' feature exists whether or not it is functional (e.g. ;; libgcc is available or not). This seems silly, as some packages will blindly -;; use the native-comp API if it's present, whether or not it's functional. so -;; pretend it doesn't exist if that's the case. +;; use the native-comp API if it's present but non-functional, so let's pretend +;; it doesn't exist if that's the case. (if (featurep 'native-compile) (if (not (native-comp-available-p)) (delq 'native-compile features))) -;; DEPRECATED remove in v3 +;; DEPRECATED: Remove in v3 (with-no-warnings (defconst IS-MAC doom--system-macos-p) (defconst IS-LINUX doom--system-linux-p) @@ -181,10 +180,10 @@ (define-obsolete-variable-alias 'doom-etc-dir 'doom-data-dir "3.0.0")) ;; HACK: Silence obnoxious obsoletion warnings about (if|when)-let in >=31. -;; These warnings are unhelpful to end-users, and so, so many packages use -;; these macros so rather than hopelessly pester them, I'll silence them. Not -;; to mention, Emacs doesn't respect `warning-suppress-types' when it comes to -;; obsoletion warnings. +;; These warnings are unhelpful to end-users, and many packages use these +;; macros, so I silence these warnings to spare users the unactionable spam. +;; Not to mention, Emacs doesn't respect `warning-suppress-types' when it +;; comes to obsoletion warnings. (put 'if-let 'byte-obsolete-info nil) (put 'when-let 'byte-obsolete-info nil) @@ -559,7 +558,7 @@ uses a straight or package.el command directly).") (when noninteractive ;; Don't generate superfluous files when writing temp buffers. (setq make-backup-files nil) - ;; Stop user config from interfering with package management. + ;; Stop user config from interfering with elisp shell scripts. (setq enable-dir-local-variables nil) ;; Reduce ambiguity, embrace specificity, enjoy predictability. (setq case-fold-search nil) @@ -571,8 +570,7 @@ uses a straight or package.el command directly).") ;; ones) abuse it to build paths for storage/cache files (instead of correctly ;; using `locate-user-emacs-file'). This change ensures that said data files ;; are never saved to the root of your emacs directory *and* saves us the -;; trouble of setting a million directory/file variables. But it may throw off -;; anyone (or any package) that uses it to search for your Emacs initfiles. +;; trouble of setting a million directory/file variables. (setq user-emacs-directory doom-profile-cache-dir) ;; ...However, this may surprise packages (and users) that read @@ -602,7 +600,7 @@ Otherwise, `en/disable-command' (in novice.el.gz) is hardcoded to write them to (when (boundp 'native-comp-eln-load-path) ;; Don't store eln files in ~/.emacs.d/eln-cache (where they can easily be ;; deleted by 'doom upgrade'). - ;; REVIEW Use `startup-redirect-eln-cache' when 28 support is dropped + ;; REVIEW: Advise `startup-redirect-eln-cache' when 28 support is dropped. (add-to-list 'native-comp-eln-load-path (expand-file-name "eln/" doom-profile-cache-dir)) ;; UX: Suppress compiler warnings and don't inundate users with their popups. @@ -610,7 +608,7 @@ Otherwise, `en/disable-command' (in novice.el.gz) is hardcoded to write them to (setq native-comp-async-report-warnings-errors init-file-debug native-comp-warning-on-missing-source init-file-debug) - ;; HACK: native-comp-deferred-compilation-deny-list is replaced in later + ;; HACK: `native-comp-deferred-compilation-deny-list' is replaced in later ;; versions of Emacs 29, and with no deprecation warning. I alias them to ;; ensure backwards compatibility for packages downstream that may have not ;; caught up yet. I avoid marking it obsolete because obsolete warnings are @@ -631,8 +629,8 @@ Otherwise, `en/disable-command' (in novice.el.gz) is hardcoded to write them to (define-advice comp-run-async-workers (:around (fn &rest args) dont-litter-tmpdir) "Normally, native-comp writes a ton to /tmp. This advice forces it to write -to `doom-cache-dir'/comp/ instead, so that Doom can safely clean it up as part -of 'doom sync' or 'doom gc'." +to `doom-profile-cache-dir' instead, so it can be safely cleaned up as part of +'doom sync' or 'doom gc'." (let ((temporary-file-directory (expand-file-name "comp/" doom-profile-cache-dir))) (make-directory temporary-file-directory t) (apply fn args))) @@ -642,7 +640,7 @@ of 'doom sync' or 'doom gc'." ;; to comp-run. See emacsmirror/emacs@e6a955d24268. Doom forces straight ;; to consult this variable when building packages. (require 'comp-run nil t) - ;; HACK Disable native-compilation for some troublesome packages + ;; HACK: Disable native-compilation for some troublesome packages (mapc (doom-partial #'add-to-list 'native-comp-deferred-compilation-deny-list) (list "/seq-tests\\.el\\'" "/emacs-jupyter.*\\.el\\'" @@ -851,12 +849,13 @@ appropriately against `noninteractive' or the `cli' context." (require 'doom-cli) (add-hook 'doom-cli-initialize-hook #'doom-finalize))) - ;; HACK: We suppress loading of site files so they can be loaded manually, - ;; here. Why? To suppress the otherwise unavoidable output they commonly - ;; produce (like deprecation notices, file-loaded messages, and linter - ;; warnings). This output pollutes the output of doom's CLI (or scripts - ;; derived from it) with potentially confusing or alarming -- but always - ;; unimportant -- information to the user. + ;; HACK: I suppress loading of site files here to load them manually later. + ;; Why? To suppress the otherwise unavoidable output they commonly produce + ;; (like deprecation notices, file-loaded messages, and linter warnings). + ;; This output pollutes Emacs' log and the output of doom's CLI (or + ;; scripts derived from it) with potentially confusing or alarming -- but + ;; always unimportant and rarely actionable -- information to the user. To + ;; see that output, turn on debug mode! (let ((site-loader (lambda () (quiet!! @@ -885,8 +884,8 @@ appropriately against `noninteractive' or the `cli' context." ;; HACK: Ensure OS checks are as fast as possible (given their ubiquity). (setq features (cons :system (delq :system features))) - ;; Remember these variables' initial values, so we can safely reset them - ;; at a later time, or consult them without fear of contamination. + ;; Remember these variables' initial values, so they can be safely reset + ;; later (e.g. by `doom/reload'), or compared against for change heuristics. (dolist (var '(exec-path load-path process-environment)) (put var 'initial-value (default-toplevel-value var)))