Now that 29.1 is stable, support for it is official. This updates or
docs and doctor checks to take this into account. I've also included a
link to a Discourse post where I track support for Emacs HEAD.
From now on, our documentation will assume your Emacs config lives in
~/.config/emacs, by default, rather than ~/.emacs.d. Support for the
latter is not going away, it will simply be mentioned less in the
literature, as all supported versions of Emacs going forward (and future
versions of Doom) will support (and prefer) XDG conventions.
The user manual will be updated separately.
Close: #6965
Co-authored-by: gagbo <gagbo@users.noreply.github.com>
`doom doctor` throws a type error for enabled modules without a
doctor.el and/or packages.el file. This occurs because, in
in775ee2f04aad, `doom-module-expand-path` was changed to return nil if
the target file did not exist, and the doctor wasn't updated to handle
this. It passes `nil` to `load`, causing this type error.
Amend: 775ee2f04a
Library packages (like compat and transient) offer macros. Therefore,
any package that uses them (dependents) needs to be recompiled when
these are updated, but straight currently doesn't do this. As a
temporary workaround, this commit forces dependents to be rebuilt after
updates.
This is a bit too brute-force, but will do until v3, which will manage
dependency graphs and their complexities more efficiently.
In case straight prompts something like the following:
> In repository "git-modes", HEAD on "master" is behind default branch "main"
1) Abort
2) Checkout "main" (Choose this if unsure)
3) Magit log "master..main" and open recursive edit
This allows for more rapid 'doom sync'ing when testing different module
combinations, but puts the onus on the user to run `doom sync
--purge` (or `doom purge`, which will later be renamed `doom gc`) to
prune orphaned packages/repos.
The doctor would look for stale byte-code in *all* build directories,
which was excessive and produced many false positives for folks who use
multiple versions of Emacs or have recently up/downgraded.
* lisp/cli/help.el (doom help): move to lisp/cli/meta.el, and add :dump
definition.
* lisp/doom-cli.el:
- (doom-before-init-hook): trigger hook after the file is done
loading.
- (doom-cli-backtrace-depth, doom-cli-straight-error-lines,
doom-cli-benchmark-threshold): rename these variables' prefix from
`doom-cli-` to `doom-cli-log-`.
- (doom-cli--plist): rename to doom-cli--group-plist, to better clue
in what changes it.
- (doom-cli-context-parse): remove unused letbind (argsleft).
- (doom-cli-create-context-functions, doom-cli-before-run-functions,
doom-cli-after-run-functions): define with defcustom instead of
defvar, to indicate that they are (especially) intended for end-user
configuration.
A regression introduced in 4efaf68, cause by an incomplete refactoring
of the loop, where not all instances of `key` were changed into `group`
and `name`.
Amend: 4efaf6837bFix: #6840
Where f9201eb introduced a general context system, this one introduces
one for modules, to simplify our let-bind game when interacting with
modules, and to more efficiently expose module state to modulep! (which
gets called at runtime a great deal, so its performance is important).
* lisp/doom-lib.el (doom-log): simplify macro and introduce
doom-inhibit-log variable.
* lisp/doom-modules.el (modulep!): fix reported file path if modulep!
fails to find the local module.
* lisp/lib/debug.el (doom-debug-variables): disable doom-inhibit-log
when debug mode is on.
Ref: f9201eb218
Introduces a system to announce what execution contexts are active, so I
can react appropriately, emit more helpful logs/warnings in the case of
issues, and throw more meaningful errors.
* bin/doom: load module CLIs in the 'modules' context.
* lisp/cli/doctor.el: load package files in 'packages' context.
* lisp/doom-cli.el:
- (doom-before-init-hook, doom-after-init-hook): trigger hooks at the
correct time. This may increase startup load time, as the benchmark
now times more of the startup process.
- (doom-cli-execute, doom-cli-context-execute,
doom-cli-context-restore, doom-cli-context-parse,
doom-cli--output-benchmark-h, doom-cli-call, doom-cli--restart,
doom-cli-load, run!): remove redundant context prefix in debug logs,
it's now redundant with doom-context, which doom-log now prefixes
them with.
* lisp/doom-lib.el (doom-log): prefix doom-context to doom-log output,
unless it starts with :.
* lisp/doom-packages.el (package!, doom-packages--read): throw error if
not used in a packages.el file or in the context of our package
manager.
* lisp/doom-profiles.el (doom-profile--generate-init-vars,
doom-profile--generate-load-modules): use modules doom-context instead
of doom-init-time to detect startup.
* lisp/doom-start.el (doom-load-packages-incrementally-h): move function
closer to end of doom-after-init-hook.
* lisp/doom.el:
- (doom-before-init-hook, doom--set-initial-values-h,
doom--begin-init-h): rename doom--set-initial-values-h to
doom--begin-init-h and ensure it runs as late in
doom-before-init-hook as possible, as that is the point where Doom's
"initialization" formally begins.
- (doom-after-init-hook): don't trigger at the end of command-line-1
in non-interactive sessions. This will be triggered manually in
doom-cli.el's run!.
* lisp/lib/config.el (doom/reload, doom/reload-autoloads,
doom/reload-env): use 'reload' context for reload commands.
* modules/lang/emacs-lisp/autoload.el (+emacs-lisp-eval): use 'eval'
context.
* modules/lang/org/config.el: remove doom-reloading-p; check for
'reload' doom context instead.
- Adds doom-module-packages-file and doom-module-metadata-file.
- Uses them and the other doom-module-*-file variables where they were
previously hardcoded.
- Add .el extension to doom-module-{init,config}-file; it is now the
consumer's responsibility to strip/change/keep the extension as they
see fit.
This introduces a depth field for modules so that they may dictate their
load order explicitly, it also treats depths <= -100 or >= 100 as
special depths, which will be loaded early, before their respective
doom-{before,after}-module-{init,config}-hook. This permits psuedo
modules like :core and :user modules to be treated as normal modules
without too many special cases.
This also fixes a module load order issue on Emacs 29 (#6813), caused by
emacs-mirror/emacs@4311bd0bd7, which changed the return value order of
hash-table-{keys,values} causing modules to be loaded in reverse order;
resulting in the loss of evil keybinds, among other things.
Other notable changes:
- Changes the data structure for module data caches from a list to a
vector. Uses less memory and permits faster lookups. Also adds two
depth fields to the front of it.
- Changes the signature of doom-module-list and doom-package-list.
- Renames doom--read-packages -> doom-packages--read for consistency
with naming convention.
- Add doom-module-depth function.
- Adds a temporary doom-core-dir/init.el file, which is responsible for
loading doom-*.el.
Fix: #6813
Ref: emacs-mirror/emacs@4311bd0bd7
- Batch more variables in Doom's autoloads files.
- Remove all the register-definition-prefixes calls generated in
autoloads files (for both modules' and packages' autoloads). These
don't serve much purpose, and only incur added cost growing a large
hash table.
Due to a technical limitation of Emacs <=28, launching Emacs out of a
non-standard location is non-trivial, and `doom run` tries to promise
that it can do so on demand. Emacs 29 does introduce a --init-directory
switch that would make this easy, but it'll be some time before we can
rely on it.
So 'doom run' creates a fake $HOME in /tmp/doom.run/ and writes a
bootloader there to load your Doom config remotely. But there's a
problem: in this fake $HOME, none of the user's config, cache, data, or
binscript directories are available, so I symlink them there. This
should at least resolve the most trivial incompatibilities (like the
lack of all-the-icons fonts, which typically get installed to
$HOME/.local/share/fonts/ -- see #6807), but there may be yet more edge
cases. Still, this is a good enough compromise for now.
Fix: #6807
- Adds $DOOMPROFILELOADFILE: Controls where to read and write the
profile loader. Changing this may be helpful for users on nix/guix,
who have deployed Doom to a read-only location. This sets
`doom-profile-load-file`.
- Changed profile load file's default location (used to be
$EMACSDIR/profiles/init.el, is now $EMACSDIR/profiles/load.el). The
gitignore was updated to reflect this.
- Adds $DOOMPROFILELOADPATH: A colon-delimited list of profile config
files and directories (semi-colon on Windows) which dictate what Doom
reads in order to discover your profiles. Config files are required to
have an *.el extension. This sets `doom-profile-load-path`.
- Changes the nomenclature around this loader script. I used to refer to
it as the profile bootstrapper. I'll now refer to it as the profile
load file, and I've renamed `doom-profiles-bootstrap-file` to
`doom-profile-load-file` to reflect this.
- The variables `doom-profile-dirs` and `doom-profile-config-files` were
merged into doom-profile-load-path.
- Both envvars have also been documented in `doom help` (and
$DOOMPROFILE's has been updated).
Ref: #6794
- Swap out the funcall+alist lookup for a pcase (which is expanded to a
cond, which is is faster and easier to read).
- Wrap bootstrap file to $EMACSDIR/profiles/init.el, but byte-compile it
to $EMACSDIR/profiles/init.X.el where X is emacs-major-version.
- Make doom-profiles-save's second argument optional (defaults to
doom-profiles-bootstrap-file).
- Make doom-profiles-save throw a error if byte-compilation fails for
some reason.
- Rename the tempvars to include 'doom' in their name, so debuggers know
where they originate.
If Doom doesn't live in ~/.emacs.d or ~/.config/emacs, then it cannot
play the role of bootloader, so opt out of generating the profile
bootstrappper in this case.
That said, don't disable the profile system entirely; it can still be
useful for internal, noninteractive, and sandbox use.
Causing the envvar file to be generated to wrong place, and thus never
be updated/properly loaded at runtime.
This new setting is for later, where I'll integrate the envvar generate
into the profile generator proper.
I forgot to add the definitions for the 'doom profile{s,}' commands in
b914830, which causes "unrecognized command 'profiles sync'" errors on
'doom {sync,upgrade}'.
My unparalleled brilliance is 4 parallel universes ahead of me, clearly.
Amend: b914830403
Each of these functions have a native-comp guard, which may be overkill,
but for the time being they should be grouped together, to indicate
their relationship.
BREAKING CHANGE: This commit makes three breaking changes:
- Doom now fully and dynamically generates (and byte-compiles) your
profile and its init files, which includes your autoloads, loading
your init files and modules, and then some. This replaces
doom-initialize-modules, doom-initialize-core-modules, and
doom-module-loader, which have been removed. This has also improved
startup time by a bit, but if you use these functions in your CLIs,
for instance, this will be a breaking change.
- `doom sync` is now required for Doom to see your profiles (and must be
run whenever you change them, or when you up/downgrade Emacs across
major versions).
- $DOOMDIR/init.el is now read much earlier than it used to be. Before
any of doom-{ui,keybinds,editor,projects}, before any autoloads are
loaded, and before your load-path has been populated with your
packages. It now runs in the context of early-init.el, giving users
freer range over what they can affect, but a more minimalistic
environment to do it in.
If you must have some logic run when all that is set up, add it to one
of the module hooks added in e08f68b or 283308a.
This also poses a significant change to Doom's load order (see the
commentary change in lib/doom.el), along with the following (non
breaking) changes:
1. Adds a new `doom profiles sync` command. This will forcibly resync
your profiles, while `doom sync` will only do so if your profiles
have changed.
2. Doom now fully and dynamically generates (and byte-compiles) your
user-init-file, which includes loading all your init files, modules,
and custom-file. This replaces the job of doom-initialize-modules,
doom-initialize-core-modules, and doom-module-loader, which have been
removed. This has also improved startup time by a bit.
3. Defines new doom-state-dir variable, though not used yet (saving that
and the other breaking changes for the 3.0 release).
4. Redesigns profile directory variables (doom-profile-*-dir) to prepare
for future XDG-compliance.
5. Removed unused/unimportant profile variables in doom.el.
6. Added lisp/doom-profiles.el. It's hardly feature complete, but it's
enough to power the system as it is now.
7. Updates the "load order" commentary in doom.el to reflect these
changes.
...that are always enabled. This way, the module API treats them as any
other module.
This also changes doom-module-load-path. If supplied directories,
doom-user-dir will not be the CAR of its return value. If no dirs are
supplied, then doom-core-dir and doom-user-dir are included (and will
always be the first two items in the returned list).
For small amounts of data, symbol plists are the most efficient (space
and time wise) as data access gets in Emacs. Hash tables, though O(1),
impose a minimum threshold of overhead before it becomes the efficient
option, but this benefit won't be obvious for datasets of at least 60 or
less.
Since modulep! is used *a lot*, and used to determine a module's
state (and state of its flags), there is a benefit to caching it.
Still, this is only a read-only cache, and does not replace the
`doom-modules` hash-table, which will always be the preferred interface
for the rest of the module API.
- Rename doom-module-path -> doom-module-expand-path, to better reflect
its purpose.
- Optimize doom-module-locate-path to try caches and
locate-file-internal, before looping through doom-modules-dirs.
- Rely on file-name-concat to join paths, rather than string
concatenation. file-name-concat is more robust for the purpose and
has lower overhead than expand-file-name.
- Add a 27.x check, recommending that users upgrade to 28.1.
- Removed the check for <27. Loading doom.el with sub-27 will already
fail with a detailed error about supported versions.
- Now detects development (.50) and pre-release (.9x) builds of Emacs,
and warns the user of their dangers.
- Revises the warning for 29+ or .50|.9x users.
This refactors how Doom captures and redirects its output (to stdout and
stderr) into a more general with-output-to! macro, and:
- Simplifies the "print level" system. The various doom-print-*-level
variables have been removed.
- Adds a new print level: notice, which will be the default level for
all standard output (from print!, doom-print, prin[ct1], etc).
- Adds a with-output-to! macro for capturing and redirecting
output to multiple streams (without suppressing it from stdout). It
can also be nested.
- Changes the following about doom-print:
- Default :format changed to nil (was t)
- Default :level changed to t (was `doom-print-level`)
- No longer no-ops if OUTPUT is only whitespace
This commit reduces the debug log noise, makes it easier to
read/parse/search, and soft-introduces a convention for doom-log
messages, where they are prefixed with a unique identifier loosely named
after it's running context or calling function.
I haven't enforced it everywhere doom-log is used yet, but this is a
start.
BREAKING CHANGE: If anyone is using Doom's CLI framework and are
defining their own CLIs with any of the following macros, they'll need
to be updated to their new names:
- defautoload! -> defcli-autoload!
- defgroup! -> defcli-group!
- defstub! -> defcli-stub!
- defalias! -> defcli-alias!
- defobsolete! -> defcli-obsolete!
These were renamed to make their relationship with CLIs more obvious;
they were too ambiguous otherwise.
