BREAKING CHANGE: This performs the following backwards-incompatible
changes:
- Replaces `+emacs-lisp-reduce-flycheck-errors-in-emacs-config-h` with a
`+emacs-lisp-non-package-mode` minor-mode.
- Removed the `+emacs-lisp-disable-flycheck-in-dirs` variable, as this
mechanism no longer checks a directory list to detect a "non-package".
If you've referenced either of these symbols, you'll need to
update/remove them from your config. No extra config is needed
otherwise.
Why: Doom has always tried to reduce the verbosity of Flycheck when
viewing elisp config files or scripts (i.e. non-packages). These are so
stateful that the byte-compiler, package-lint, and checkdoc inundate
users with false positives that are more overwhelming than helpful.
The heuristic for this has always been a simple "is this file in
$DOOMDIR or $EMACSDIR", but this wasn't robust enough, especially in
cases where symlinking was involved, so I've employed a new, more
general heuristic for detecting non-package files:
- The file isn't a theme in `custom-theme-load-path`,
- The file doesn't have a (provide ...) or (provide-theme ...)
statement whose first argument matches the file name,
- The file lives in a project with a .doommodule file (doom modules
never have convention package files in them),
- Or the file is a dotfile (like .dir-locals.el or .doomrc).
I've also tweaked byte-compile-warnings to yield a little more output,
but not by much. Whether this is too permissive or not will require
further testing to determine.
What's more, I've updated this to reflect recent changes to Doom's
startup process (in c05e615).
Ref: c05e61536e
- Deprecates the doom-private-dir variable in favor of doom-user-dir.
- Renames the pseudo category for the user's module: :private -> :user.
- Renames the doom-private-error error type to doom-user-error.
Emacs uses the term "user" to refer to the "things" in user space (e.g.
user-init-file, user-emacs-directory, user-mail-address, xdg-user-dirs,
package-user-dir, etc), and I'd like to be consistent with that. It also
has the nice side-effect of being slightly shorter. I also hope
'doom-user-error' will be less obtuse to beginners than
'doom-private-error'.
featurep! will be renamed modulep! in the future, so it's been
deprecated. They have identical interfaces, and can be replaced without
issue.
featurep! was never quite the right name for this macro. It implied that
it had some connection to featurep, which it doesn't (only that it was
similar in purpose; still, Doom modules are not features). To undo such
implications and be consistent with its namespace (and since we're
heading into a storm of breaking changes with the v3 release anyway),
now was the best opportunity to begin the transition.
Typically caused by partial syntax errors in Doom Emacs (e.g. while
you're writing code in $EMACSDIR or $DOOMDIR, and haven't typed the
closing parenthesis yet).
I've omitted docs/*.org from this merge, as there is still work left to
do there, but I am pushing the module docs early so folks can benefit
from the new docs sooner.
BREAKING CHANGE: This restructures the project in preparation for Doom
to be split into two repos. Users that have reconfigured Doom's CLI
stand a good chance of seeing breakage, especially if they've referred
to any core-* feature, e.g.
(after! core-cli-ci ...)
To fix it, simply s/core-/doom-/, i.e.
(after! doom-cli-ci ...)
What this commit specifically changes is:
- Renames all core features from core-* to doom-*
- Moves core/core-* -> lisp/doom-*
- Moves core/autoloads/* -> lisp/lib/*
- Moves core/templates -> templates/
Ref: #4273
BREAKING CHANGE: this changes Doom's CLI framework in subtle ways, which
is listed in greater detail below. If you've never extended Doom's CLI,
then this won't affect you, but otherwise it'd be recommended you read
on below.
This commit focuses on the CLI framework itself and backports some
foundational changes to its DSL and how it resolves command line
arguments to CLIs, validates input, displays documentation, and persists
state across sessions -- and more. This is done in preparation for the
final stretch towarding completing the CLI rewrite (see #4273).
This is also an effort to generalize Doom's CLI (both its framework and
bin/doom), to increase it versatility and make it a viable dev tool for
other Doom projects (on our Github org) and beyond.
However, there is a *lot* to cover so I'll try to be brief:
- Refactor: generalize Doom's CLI framework by moving all bin/doom
specific configuration/commands out of core-cli into bin/doom. This
makes it easier to use bin/doom as a project-agnostic development
tool (or for users to write their own).
- Refactor: change the namespace for CLI variables/functions from
doom-cli-X to doom-X.
- Fix: subcommands being mistaken as arguments. "doom make index" will
resolve to (defcli! (doom make index)) if it exists,
otherwise (defcli! (doom make)) with "index" as an argument. Before
this, it would resolve to the latter no matter what. &rest can
override this; with (defcli! (doom make) (&rest args)), (defcli! (doom
make index)) will never be invoked.
- Refactor!: redesign our output library (was core/autoload/output.el,
is now core/autoload/print.el), and how our CLI framework buffers and
logs output, and now merges logs across (exit! ...) restarts.
- Feat: add support for :before and :after pseudo commands. E.g.
(defcli! (:before doom help) () ...)
(defcli! (:after doom sync) () ...)
Caveat: unlike advice, only one of each can be defined per-command.
- Feat: option arguments now have rudimentary type validation (see
`doom-cli-option-arg-types`). E.g.
(defcli! (doom foo) ((foo ("--foo" num))) ...)
If NUM is not a numeric, it will throw a validation error.
Any type that isn't in `doom-cli-option-arg-types` will be treated as a
wildcard string type. `num` can also be replaced with a specification,
e.g. "HOST[:PORT]", and can be formatted by using symbol quotes:
"`HOST'[:`PORT']".
- Feat: it is no longer required that options *immediately* follow the command
that defines them (but it must be somewhere after it, not before). E.g.
With:
(defcli! (:before doom foo) ((foo ("--foo"))) ...)
(defcli! (doom foo baz) () ...)
Before:
FAIL: doom --foo foo baz
GOOD: doom foo --foo baz
FAIL: doom foo baz --foo
After:
FAIL: doom --foo foo baz
GOOD: doom foo --foo baz
GOOD: doom foo baz --foo
- Refactor: CLI session state is now kept in a doom-cli-context struct (which
can be bound to a CLI-local variable with &context in the arglist):
(defcli! (doom sync) (&context context)
(print! "Command: " (doom-cli-context-command context)))
These contexts are persisted across sessions (when restarted). This is
necessary to support seamless script restarting (i.e. execve
emulation) in post-3.0.
- Feat: Doom's CLI framework now understands "--". Everything after it will be
treated as regular arguments, instead of sub-commands or options.
- Refactor!: the semantics of &rest for CLIs has changed. It used to be "all
extra literal, non-option arguments". It now means *all* unprocessed
arguments, and its use will suppress "unrecognized option" errors, and
tells the framework not to process any further subcommands. Use &args
if you just want "all literal arguments following this command".
- Feat: add new auxiliary keywords for CLI arglists: &context, &multiple,
&flags, &args, &stdin, &whole, and &cli.
- &context SYM: binds the currently running context to SYM (a
`doom-cli-context` struct). Helpful for introspection or passing
along state when calling subcommands by hand (with `call!`).
- &stdin SYM: SYM will be bound to a string containing any input piped
into the running script, or nil if none. Use
`doom-cli-context-pipe-p` to detect whether the script has been
piped into or out of.
- &multiple OPTIONS...: allows all following OPTIONS to be repeated. E.g. "foo
-x a -x b -x c" will pass (list ("-x" . "a") ("-x" . "b") ("-x" .
"c")) as -x's value.
- &flags OPTIONS...: All options after "&flags" get an implicit --no-* switch
and cannot accept arguments. Will be set to :yes or :no depending on which flag is
provided, and nil if the flag isn't provided. Otherwise, a default
value can be specified in that options' arglist. E.g.
(defcli! (doom foo) (&flags (foo ("--foo" :no))) ...)
When called, this command sets FOO to :yes if --foo, :no if --no-foo, and
defaults to :no otherwise.
- &args SYM: this replaces what &rest used to be; it binds to SYM a
list of all unprocessed (non-option) arguments.
- &rest SYM: now binds SYM to a list of all unprocessed arguments, including
options. This also suppresses "unrecognized option" errors, but will render
any sub-commands inaccessible. E.g.
(defcli! (doom make) (&rest rest) ...)
;; These are now inaccessible!
(defcli! (doom make foo) (&rest rest) ...)
(defcli! (doom make bar) (&rest rest) ...)
- &cli SYM: binds SYM to the currently running `doom-cli` struct. Can also be
obtained via `(doom-cli-get (doom-cli-context-command context))`. Possibly
useful for introspection.
- feat: add defobsolete! macro for quickly defining obsolete commands.
- feat: add defalias! macro for quickly defining alias commands.
- feat: add defautoload! macro for defining an autoloaded command (won't
be loaded until it is called for).
- refactor!: rename defcligroup! to defgroup! for consistency.
- fix: CLIs will now recursively inherit plist properties from parent
defcli-group!'s (but will stack :prefix).
- refactor!: remove obsolete 'doom update':
- refactor!: further generalize 'doom ci'
- In an effort to generalize 'doom ci' (so other Doom--or
non-doom--projects can use it), all its subcommands have been
changed to operate on the current working directory's repo instead
of $EMACSDIR.
- Doom-specific CI configuration was moved to .github/ci.el.
- All 'doom ci' commands will now preload one of \$CURRENT_REPO_ROOT/ci.el or
\$DOOMDIR/ci.el before executing.
- refactor!: changed 'doom env'
- 'doom env {-c,--clear}' is now 'doom env {clear,c}'
- -r/--reject and -a/--allow may now be specified multiple times
- refactor!: rewrote CLI help framework and error handling to be more
sophisticated and detailed.
- feat: can now initiate $PAGER on output with (exit! :pager) (or use
:pager? to only invoke pager is output is longer than the terminal is
tall).
- refactor!: changed semantics+conventions for global bin/doom options
- Single-character global options are now uppercased, to distinguish them from
local options:
- -d (for debug mode) is now -D
- -y (to suppress prompts) is now -!
- -l (to load elisp) is now -L
- -h (short for --help) is now -?
- Replace --yes/-y switches with --force/-!
- -L/--load FILE: now silently ignores file errors.
- Add --strict-load FILE: does the same as -L/--load, but throws an error if
FILE does not exist/is unreadable.
- Add -E/--eval FORM: evaluates arbitrary lisp before commands are processed.
- -L/--load, --strict-load, and -E/--eval can now be used multiple times in
one command.
- Add --pager COMMAND to specify an explicit pager. Will also obey
$DOOMPAGER envvar. Does not obey $PAGER.
- Fix#3746: which was likely caused by the generated post-script overwriting
the old mid-execution. By salting the postscript filenames (with both an
overarching session ID and a step counter).
- Docs: document websites, environment variables, and exit codes in
'doom --help'
- Feat: add imenu support for def{cli,alias,obsolete}!
Ref: #4273Fix: #3746Fix: #3844
This fix ensures that functions/macros that are evaluated with +eval/*
et co will remember where they were defined (if possible), so you don't
have to see this in their documentation again:
FUNCTION is a function without a source file.
Ref: https://github.com/doomemacs/doomemacs/pull/6444#issuecomment-1159457888
When evaluating from a buffer not visiting any file, file-truename would
error out since the argument it was fed is nil.
Fix: #6181Close: #6404
Ref: 7290f85cfd
Co-authored-by: Yoav Marco <ymarco@users.noreply.github.com>
add-hook! is advertised to be able to add multiple hooks using a
function-quoted list of functions, but add-hook! never actually
supported this. Rather than correct the implementation, I'm correcting
the documentation instead, because sharp-quoting lists betrays the
semantics of the sharp-quote. Quoted lists should still work fine
though (as documented in add-hook!'s docstring).
Close: #5843
Fewer links means less confusion.
- Merge doom-issue and doom-commit links into doom-ref (for auto-linking
Issue/PR/commit references).
- Merge doom-module-source and doom-docs-source links into doom-source.
- Rename doom-report-issue to doom-report.
- Use '!' as the icon for module issues link.
- Remove doom-repo (replaced with "doom:*" in :lang org module).
- Add doomdir and emacsdir links to :lang org module.
From now on Doom will enforce two conventions for its org files for
consistency's sake:
- Lower-case meta-lines in org files, like #+begin_src, #+name, or
#+end_quote (only exception are the top-level ones, like #+TITLE and
#+STARTUP).
- Use 'emacs-lisp' as the lang specifier for elisp blocks rather than
'elisp'. Emacs doesn't natively recognize the latter.
This will be reflected in our rewritten docs/*.org and module
README.org's.
It's hardcoded to return t for symbols that end in any of '-command',
'-frame-alist', '-function', '-functions', '-hook', '-hooks', '-form',
'-forms', '-map', '-map-alist', '-mode-alist', '-program', or
'-predicate' -- which I think is excessive next to a safety check.
I'll trust that: if the user marks X as safe, and it isn't *explicitly*
marked risky, and it destroys the universe, then it's their fault, not
mine, not Emacs'.
This suppresses the annoying "do you want to apply these unsafe file/dir
local variables" prompt by ignoring them (but stills them so at least
users are told).
Fixes issue mentioned in #4335
Without `deferred', the file selected in the `counsel-find-file' will
only remain the current buffer afterwards when pressing RET on an item,
not just `ivy-call'.
