-
-
-
- 
-
-
- 
-
-
- 
-
-- Screenshots - | - Get started - | - Contribute - | - Documentation - | - FAQ -
+
+
+
+> It is a story as old as time. A stubborn, shell-dwelling, and melodramatic
+> vimmer -- envious of the features of modern text editors -- spirals into
+> despair before he succumbs to the [dark side][evil-mode]. This is his config.
+
+Doom is a configuration framework for [GNU Emacs] tailored for Emacs bankruptcy
+veterans who want less framework in their frameworks, a modicum of stability
+(and reproducibility) from their package manager, and the performance of a hand
+rolled config (or better). It can be a foundation for your own config or a
+resource for Emacs enthusiasts to learn more about our favorite operating
+system.
+
+Its design is guided by these mantras:
+
++ **Gotta go fast.** Startup and run-time performance are priorities. Doom goes
+ beyond by modifying packages to be snappier and load lazier.
++ **Close to metal.** There's less between you and vanilla Emacs by design.
+ That's less to grok and less to work around when you tinker. Internals ought
+ to be written as if reading them were part of Doom's UX, and it is!
++ **Opinionated, but not stubborn.** Doom is about reasonable defaults and
+ curated opinions, but use as little or as much of it as you like.
++ **Your system, your rules.** You know better. At least, Doom hopes so! It
+ won't *automatically* install system dependencies (and will force plugins not
+ to either). Rely on `doom doctor` to tell you what's missing.
++ **Nix/Guix was a great idea!** The Emacs ecosystem is temperamental. Things
+ break and they break often. Disaster recovery should be a priority! Doom's
+ package management should be declarative and your private config reproducible,
+ and comes with a means to roll back releases and updates (still a WIP).
+
+Check out [the FAQ][FAQ] for answers to common questions about the project.
+
+
+# Features
+- Minimalistic good looks inspired by modern editors.
+- Curated and sane defaults for many packages, (major) OSes, and Emacs itself.
+- A modular organizational structure for separating concerns in your config.
+- A standard library designed to simplify your elisp bike shedding.
+- A declarative [package management system][package-management] (powered by
+ [straight.el]) with a command line interface. Install packages from anywhere,
+ not just (M)ELPA, and pin them to any commit.
+- Optional vim emulation powered by [evil-mode], including ports of popular vim
+ plugins like [vim-sneak], [vim-easymotion], [vim-unimpaired] and
+ [more][ported-vim-plugins]!
+- Opt-in LSP integration for many languages, using [lsp-mode].
+- Support for *many* programming languages. Includes syntax highlighting,
+ linters/checker integration, inline code evaluation, code completion (where
+ possible), REPLs, documentation lookups, snippets, and more!
+- Support for *many* tools, like docker, pass, ansible, terraform, and more.
+- A Spacemacs-esque [keybinding scheme][bindings], centered around leader
+ and localleader prefix keys (SPC and SPCm for
+ evil users, C-c and C-c l for vanilla users).
+- A rule-based [popup manager][popup-system] to control how temporary buffers
+ are displayed (and disposed of).
+- Per-file indentation style detection and [editorconfig] integration. Let
+ someone else can argue about tabs vs **_spaces_**.
+- Project-management tools and framework-specific minor modes with their own
+ snippets libraries.
+- Project search (and replace) utilities, powered by [ripgrep] and [ivy] or
+ [helm].
+- Isolated and persistent workspaces (also substitutes for vim tabs).
+- Support for Chinese and Japanese input systems.
+- Save a snapshot of your shell environment to a file for Emacs to load at
+ startup. No more struggling to get Emacs to inherit your `PATH`, among other
+ things.
+
+
+# Prerequisites
++ Git 2.23+
++ Emacs 26.1+ *(27 is recommended)* with GNUTLS support
++ [ripgrep] 11.0+
++ GNU `find`
++ *OPTIONAL:* [fd] 7.3.0+ (improves file indexing performance for some commands)
+
+Doom is comprised of [~150 optional modules][Modules], some of which may have
+additional dependencies. [Visit their documentation][Modules] or run `bin/doom
+doctor` to check for any that you may have missed.
+
+
+# Install
+``` sh
+git clone --depth 1 https://github.com/hlissner/doom-emacs ~/.emacs.d
~/.emacs.d/bin/doom install
```
-More details, including dependencies and how to install Emacs, can be found [in
-the documentation](docs/getting_started.org#install).
+Then [read our Getting Started guide][documentation] to be walked through
+setting up, configuring and maintaining Doom Emacs.
-**Table of Contents**
+It's a good idea to add `~/.emacs.d/bin` to your `PATH`! Other `bin/doom`
+commands you should know about:
-- [What is Doom Emacs](#what-is-doom-emacs)
- - [Doom's mantras](#dooms-mantras)
- - [Features](#features)
-- [Getting Help](#getting-help)
- - [Community](#community)
- - [Troubleshooting](#troubleshooting)
- - [Contributing](#contributing)
++ `doom sync` to synchronize your private config with Doom. Installs new
+ packages, removes orphaned packages and regenerates caches. Run this whenever
+ you modify your private `init.el` or `packages.el`, or install/remove an Emacs
+ package through your OS package manager (e.g. mu4e or agda).
++ `doom upgrade` to update Doom to the latest release & all installed packages.
++ `doom doctor` to diagnose common issues with your system and config.
++ `doom env` to dump a snapshot of your shell environment to a file that Doom
+ will load at startup. This allows Emacs to inherit your `PATH`, among other
+ things.
++ `doom build` to recompile all installed packages (use this if you up/downgrade
+ Emacs).
-# What is Doom Emacs
-
- 
-
+# Roadmap
+Doom is an active and ongoing project. To make that development more
+transparent, its roadmap (and other concerns) are published across three github
+project boards and a newsletter:
-It is a story as old as time. A stubborn, shell-dwelling, and melodramatic as
-vimmer -- envious of the features of modern text editors -- spirals into despair
-before succumbing to the [dark side][url:evil-mode]. This is his config.
++ [Development Roadmap](/projects/3): roughly outlines our goals between release
+ milestones and their progress.
++ [Plugins under review](/projects/2): lists plugins we are watching and
+ considering for inclusion, and what their status for inclusion is. Please
+ consult this list before requesting new packages/features.
++ [Upstream bugs](/projects/5): lists issues that originate from elsewhere, and
+ whether or not we have local workarounds or temporary fixes for them.
++ ~~Doom's newsletter~~ (not finished) will contain changelogs in between
+ releases.
+
-Doom is a configuration framework for [GNU
-Emacs](https://www.gnu.org/software/emacs/) tailored for Emacs bankruptcy
-veterans who want less framework in their frameworks and the performance of a
-hand rolled config (or better). It can be a foundation for your own config or a
-resource for Emacs enthusiasts to learn more about our favorite OS.
+# Getting help
+Emacs is no journey of a mere thousand miles. You _will_ run into problems and
+mysterious errors. When you do, here are some places you can look for help:
-## Doom's mantras
++ [Our documentation][documentation] covers many use cases.
+ + [The Configuration section][configuration] covers how to configure Doom and
+ its packages.
+ + [The Package Management section][package-management] covers how to install
+ and disable packages.
+ + [This section][bin/doom] explains the `bin/doom` script's most important
+ commands.
+ + [This section][common-mistakes] lists some common configuration mistakes new
+ users make, when migrating a config from another distro or their own.
+ + [This answer][change-theme] shows you how to add your own themes to your
+ private config.
+ + [This answer][change-font] shows you how to change the default font.
+ + Your issue may be documented in the [FAQ].
++ With Emacs built-in help system documentation is a keystroke away:
+ + For functions: `SPC h f` or `C-h f`
+ + For variables: `SPC h v` or `C-h v`
+ + For a keybind: `SPC h k` or `C-h k`
+ + To search available keybinds: `SPC h b b` or `C-h b b`
++ Run `bin/doom doctor` to detect common issues with your development
+ environment and private config.
++ Check out the [FAQ], in case your question has already been answered.
++ Search [Doom's issue tracker](/issues) in case your issue was already
+ reported.
++ Hop on [our Discord server][discord]; it's active and friendly! Keep an eye on
+ the #announcements channel, where I announce breaking updates and releases.
-- **Gotta go fast.** Startup and run-time performance are priorities. Doom goes
- beyond lazy loading packages by modifying them to be snappier and load lazier!
-- **Close to metal.** There's less between you and vanilla Emacs by design.
- There's less to grok, on top of Emacs.
-- **Readability counts.** Internals ought to be written as if reading them were
- part of the user experience, and it is! Modules should be syntactically sweet.
- Backend logic should be functional (as much as elisp permits), abstraction
- light and (hopefully) documented.
-- **Opinionated, but not stubborn.** Doom is a bundle of reasonable defaults and
- curated opinions, but all of it should be optional. Use as little or as much
- of it as you like.
-- **Your system, your rules.** There are more ways to set up your development
- environment than there are dislikes on Youtube Rewind '18, so Doom leaves it
- to you. Doom will not *automatically* install system dependencies (and will
- coerce its plugins not to do so either). Use `doom doctor` to figure out
- what's missing.
-## Features
+# Contribute
+[](http://makeapullrequest.com)
+[](https://github.com/bbatsov/emacs-lisp-style-guide)
+[][liberapay]
+[][paypal]
-- Minimalistic good looks inspired by modern editors.
-- A modular architecture for a more organized Emacs configuration.
-- A custom elisp library to help simplify your config.
-- (Optional) Vim-emulation powered by [evil-mode][url:evil-mode], including
- ports of popular vim plugins and functionality.
-- A declarative [package management system][doom:packages] (powered by
- [straight.el][url:straight]) with a command line interface. Install packages
- from anywhere, not just (M)ELPA.
-- A curated set of sane defaults for all packages, all (major) OSes, and Emacs
- itself.
-- Support for *many* programming languages. Too many to list. Includes syntax
- highlighting, linters/checker integration, inline code evaluation, code
- completion (where possible), REPLs, documentation lookups, snippets, and more!
-- Support for *many* tools, like docker, pass, ansible, terraform, and more.
-- A Spacemacs-esque [keybinding scheme][doom:bindings], centered around leader
- and localleader prefix keys (SPC and SPCm, by
- default).
-- A rule-based [popup management system][doom:popups] that dictates how
- temporary or disposable buffers are displayed (and disposed of).
-- Automatic indentation detection and [editorconfig][url:editorconfig]
- integration. Let someone else argue about tabs vs **\_\***spaces**\*\_**.
-- Project-management tools and framework-specific minor modes with their own
- snippets libraries.
-- Project search (and replace) utilities, powered by [ripgrep][url:ripgrep].
-- Isolated and persistent workspaces (also substitutes for vim tabs).
-- An envvar file generator that captures a snapshot of your shell environment
- for Doom to load at startup. No more struggling to get Emacs to inherit your
- `PATH`, among other things.
+Doom is a labor of love and incurable madness, but I'm only one guy. Doom
+wouldn't be where it is today without your help. I welcome contributions of any
+kind!
-# Getting Help
++ I :heart: pull requests and bug reports (see the [Contributing
+ Guidelines][contribute])!
++ Don't hesitate to [tell me my Elisp-fu sucks](/issues/new), but please tell me
+ why.
++ Hop on [our Discord server][Discord] and say hi! Help others, hang out or talk
+ to me about Emacs, gamedev, programming, physics, pixel art, anime, gaming --
+ anything you like. Nourish this lonely soul.
++ If you'd like to support my work financially, buy me a drink through
+ [liberapay] or [paypal]. My work contends with studies, adventures in indie
+ gamedev and freelance work. Donations help me allocate more time to my Emacs
+ and OSS capers.
+
+[](https://sourcerer.io/fame/hlissner/hlissner/doom-emacs/links/0)
+[](https://sourcerer.io/fame/hlissner/hlissner/doom-emacs/links/1)
+[](https://sourcerer.io/fame/hlissner/hlissner/doom-emacs/links/2)
+[](https://sourcerer.io/fame/hlissner/hlissner/doom-emacs/links/3)
+[](https://sourcerer.io/fame/hlissner/hlissner/doom-emacs/links/4)
+[](https://sourcerer.io/fame/hlissner/hlissner/doom-emacs/links/5)
+[](https://sourcerer.io/fame/hlissner/hlissner/doom-emacs/links/6)
+[](https://sourcerer.io/fame/hlissner/hlissner/doom-emacs/links/7)
-## Community
-We have [a Discord server][url:discord]! Hop on and say hi!
+[contribute]: docs/contributing.org
+[discord]: https://discord.gg/qvGgnVx
+[documentation]: docs/index.org
+[faq]: docs/faq.org
+[install]: docs/getting_started.org#install
+[backtrace]: docs/getting_started.org#how-to-extract-a-backtrace-from-an-error
+[configuration]: docs/getting_started.org#configuring-doom
+[package-management]: docs/getting_started.org#package-management
+[bin/doom]: docs/getting_started.org#the-bindoom-utility
+[common-mistakes]: docs/getting_started.org#common-mistakes-when-configuring-doom-emacs
+[change-theme]: docs/faq.org#how-do-i-change-the-theme
+[change-font]: docs/faq.org#how-do-i-change-the-fonts
+[modules]: docs/modules.org
+[popup-system]: modules/ui/popup/README.org
+[screenshots]: #screenshots
+[website]: https://doomemacs.org
-## Troubleshooting
+[bindings]: modules/config/default/+evil-bindings.el
+[editorconfig]: http://editorconfig.org/
+[evil-mode]: https://github.com/emacs-evil/evil
+[fd]: https://github.com/sharkdp/fd
+[gnu emacs]: https://www.gnu.org/software/emacs/
+[helm]: https://github.com/emacs-helm/helm
+[ivy]: https://github.com/abo-abo/swiper
+[lsp-mode]: https://github.com/emacs-lsp/lsp-mode
+[nix]: https://nixos.org
+[ported-vim-plugins]: modules/editor/evil/README.org#ported-vim-plugins
+[ripgrep]: https://github.com/BurntSushi/ripgrep
+[straight.el]: https://github.com/raxod502/straight.el
+[vim-easymotion]: https://github.com/easymotion/vim-easymotion
+[vim-lion]: https://github.com/tommcdo/vim-lion
+[vim-sneak]: https://github.com/justinmk/vim-sneak
+[vim-unimpaired]: https://github.com/tpope/vim-unimpaired
-Encountered strange behavior or an error? Here are some things to try before you
-shoot off that bug report:
-
-- Run `bin/doom sync`. This ensures Doom is properly set up and its autoloads
- files are up-to-date.
-- If you have byte-compiled your config (with `bin/doom compile`), see if
- `bin/doom clean` makes the issue go away. Never debug issues with a
- byte-compiled config, it will make your job harder.
-- Run `bin/doom doctor` to detect common issues in your development environment.
-- Search Doom's issue tracker for mention of any error messages you've received.
-- [Visit our FAQ][docs:faq] to see if your issue is listed.
-
-If all else fails, [file that bug report][github:new-issue]! Please include the
-behavior you've observed, the behavior you expected, and any error messages or
-warnings logged to the \*Messages\* buffer (can be opened with SPC h
-e or `M-x view-echo-area-messages`).
-
-It's a great help if you included a backtrace with errors, i.e. `M-x
-toggle-debug-on-error` then recreating the error(s).
-
-## Contributing
-
-Doom (and my Emacs work in general) is a labor of love and incurable madness,
-done on my spare time. If you'd like to support my work, there are many things
-you can do to help; I welcome any contribution!
-
-- I love pull requests and bug reports. Check out the [Contributing
- Guidelines][docs:contributing] to find out how you can help out.
-- I welcome Elisp pointers! Don't hesitate to [tell me my Elisp-fu
- sucks][github:new-issue] (but please tell me why).
-- Hop on [our Discord server][url:discord] and say hi! Help others out, hang out
- or talk to me about Emacs, or gamedev, or programming, machine learning,
- physics, pixel art, anime, gaming -- anything you like. Nourish this lonely
- soul!
-- If you'd like to support my work financially, consider buying me a drink
- through [liberapay][url:liberapay] or [paypal][url:paypal]. Donations are a
- great help. My work here contends with studies, ventures in indie gamedev, and
- my freelance work.
-
-[docs:wiki]: docs/index.org
-[docs:wiki-quickstart]: docs/getting_started.org
-[docs:wiki-modules]: docs/index.org#Module%20List
-[docs:wiki-customization]: docs/getting_started.org#Customize
-[docs:contributing]: docs/contributing.org
-[docs:faq]: docs/faq.org
-[github:new-issue]: https://github.com/hlissner/doom-emacs/issues/new
-[doom:bindings]: modules/config/default/+evil-bindings.el
-[doom:packages]: core/autoload/packages.el
-[doom:popups]: modules/ui/popup/README.org
-[url:discord]: https://discord.gg/qvGgnVx
-[url:liberapay]: https://liberapay.com/hlissner/donate
-[url:paypal]: https://paypal.me/henriklissner/10
-[url:editorconfig]: http://editorconfig.org/
-[url:evil-mode]: https://github.com/emacs-evil/evil
-[url:ripgrep]: https://github.com/BurntSushi/ripgrep
-[url:straight]: https://github.com/raxod502/straight.el
+[liberapay]: https://liberapay.com/hlissner/donate
+[paypal]: https://paypal.me/henriklissner/10
diff --git a/core/autoload/config.el b/core/autoload/config.el
index d465d66f4..cacd0d32d 100644
--- a/core/autoload/config.el
+++ b/core/autoload/config.el
@@ -53,8 +53,8 @@ And jumps to your `doom!' block."
;;
;;; Managements
-(cl-defmacro doom--compile (command &key on-success on-failure)
- (declare (indent defun))
+(defmacro doom--if-compile (command on-success &optional on-failure)
+ (declare (indent 2))
`(with-current-buffer (compile ,command)
(add-hook
'compilation-finish-functions
@@ -76,19 +76,20 @@ Runs `doom-reload-hook' afterwards."
(interactive)
(require 'core-cli)
(when (and IS-WINDOWS (file-exists-p doom-env-file))
- (warn "Can't regenerate envvar file from within Emacs. Run 'doom env' from the console"))
- (doom--compile (format "%s sync -e" doom-bin)
- :on-success
- (let ((doom-reloading-p t))
- (doom-initialize 'force)
- (with-demoted-errors "PRIVATE CONFIG ERROR: %s"
- (general-auto-unbind-keys)
- (unwind-protect
- (doom-initialize-modules 'force)
- (general-auto-unbind-keys t)))
- (run-hook-wrapped 'doom-reload-hook #'doom-try-run-hook)
- (print! (success "Config successfully reloaded!")))
- :on-failure
+ (message "Can't regenerate envvar file from within Emacs. Run 'doom env' from the console"))
+ ;; In case doom/reload is run before incrementally loaded packages are loaded,
+ ;; which could cause odd load order issues.
+ (mapc #'require (cdr doom-incremental-packages))
+ (doom--if-compile (format "%s sync -e" doom-bin)
+ (let ((doom-reloading-p t))
+ (doom-initialize 'force)
+ (with-demoted-errors "PRIVATE CONFIG ERROR: %s"
+ (general-auto-unbind-keys)
+ (unwind-protect
+ (doom-initialize-modules 'force)
+ (general-auto-unbind-keys t)))
+ (run-hook-wrapped 'doom-reload-hook #'doom-try-run-hook)
+ (print! (success "Config successfully reloaded!")))
(user-error "Failed to reload your config")))
;;;###autoload
@@ -119,25 +120,22 @@ imported into Emacs."
(interactive "P")
(when IS-WINDOWS
(user-error "Cannot reload envvar file from within Emacs on Windows, run it from cmd.exe"))
- (doom--compile
- (format "%s -ic '%s env%s'"
- (string-trim
- (shell-command-to-string
- (format "getent passwd %S | cut -d: -f7"
- (user-login-name))))
- doom-bin (if arg " -c" ""))
- :on-success
- (let ((doom-reloading-p t))
- (unless arg
- (doom-load-envvars-file doom-env-file)))
- :on-failure
+ (doom--if-compile
+ (format "%s -ic '%s env%s'"
+ (string-trim
+ (shell-command-to-string
+ (format "getent passwd %S | cut -d: -f7"
+ (user-login-name))))
+ doom-bin (if arg " -c" ""))
+ (let ((doom-reloading-p t))
+ (unless arg
+ (doom-load-envvars-file doom-env-file)))
(error "Failed to generate env file")))
;;;###autoload
(defun doom/upgrade ()
"Run 'doom upgrade' then prompt to restart Emacs."
(interactive)
- (doom--compile (format "%s upgrade" doom-bin)
- :on-success
- (when (y-or-n-p "You must restart Emacs for the upgrade to take effect.\n\nRestart Emacs?")
- (doom/restart-and-restore))))
+ (doom--if-compile (format "%s -y upgrade" doom-bin)
+ (when (y-or-n-p "You must restart Emacs for the upgrade to take effect.\n\nRestart Emacs?")
+ (doom/restart-and-restore))))
diff --git a/core/autoload/debug.el b/core/autoload/debug.el
index bd2f241d6..7b3f5ddcd 100644
--- a/core/autoload/debug.el
+++ b/core/autoload/debug.el
@@ -184,15 +184,45 @@ markdown and copies it to your clipboard, ready to be pasted into bug reports!"
;;;###autoload
(defun doom/am-i-secure ()
- "Test to see if your root certificates are securely configured in emacs."
+ "Test to see if your root certificates are securely configured in emacs.
+Some items are not supported by the `nsm.el' module."
(declare (interactive-only t))
(interactive)
(unless (string-match-p "\\_