256 lines
13 KiB
Markdown
256 lines
13 KiB
Markdown
<div align="center">
|
||
|
||
# Doom Emacs
|
||
|
||
[Install](#install) • [Documentation] • [FAQ] • [Screenshots] • [Contribute](#contribute)
|
||
|
||
|
||
|
||
|
||
|
||
[][Discord]
|
||
[][Discourse]
|
||
|
||
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
### Table of Contents
|
||
- [Introduction](#introduction)
|
||
- [Features](#features)
|
||
- [Prerequisites](#prerequisites)
|
||
- [Install](#install)
|
||
- [Roadmap](#roadmap)
|
||
- [Getting help](#getting-help)
|
||
- [Contribute](#contribute)
|
||
|
||
|
||
# Introduction
|
||
<a href="http://ultravioletbat.deviantart.com/art/Yay-Evil-111710573">
|
||
<img src="https://raw.githubusercontent.com/doomemacs/doomemacs/screenshots/cacochan.png" align="right" />
|
||
</a>
|
||
|
||
> 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 is 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] or [eglot]
|
||
- 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 (<kbd>SPC</kbd> and <kbd>SPC</kbd><kbd>m</kbd> for
|
||
evil users, <kbd>C-c</kbd> and <kbd>C-c l</kbd> 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 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 27.1–29.3 (**Recommended: 29.3 +
|
||
[native-comp](https://www.emacswiki.org/emacs/GccEmacs)**)
|
||
- [ripgrep] 11.0+
|
||
- GNU `find`
|
||
- *OPTIONAL:* [fd] 7.3.0+ (improves file indexing performance for some commands)
|
||
|
||
> [!WARNING]
|
||
> Unstable and pre-release builds of Emacs -- which end in `.50`, `.60`, or
|
||
> `.9X` (e.g. `28.1.91`) -- **are not officially supported**. There *is* some
|
||
> effort to support Emacs HEAD, however. [Follow this Discourse
|
||
> post](https://discourse.doomemacs.org/t/3241) for details.
|
||
|
||
> [!IMPORTANT]
|
||
> 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/doomemacs/doomemacs ~/.config/emacs
|
||
~/.config/emacs/bin/doom install
|
||
```
|
||
|
||
Then [read our Getting Started guide][getting-started] to be walked through
|
||
installing, configuring and maintaining Doom Emacs.
|
||
|
||
It's a good idea to add `~/.config/emacs/bin` to your `PATH`! Other `bin/doom`
|
||
commands you should know about:
|
||
|
||
+ `doom sync` to synchronize your private config with Doom by installing missing
|
||
packages, removing orphaned packages, and regenerating 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.
|
||
|
||
|
||
# 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:
|
||
|
||
+ [Development Roadmap](https://discourse.doomemacs.org/t/development-roadmap/42):
|
||
roughly outlines our goals between release milestones and their progress.
|
||
+ [Plugins under review](https://github.com/orgs/doomemacs/projects/5):
|
||
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](https://github.com/orgs/doomemacs/projects/7): 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.
|
||
|
||
|
||
# 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:
|
||
|
||
+ [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: <kbd>SPC h f</kbd> or <kbd>C-h f</kbd>
|
||
+ For variables: <kbd>SPC h v</kbd> or <kbd>C-h v</kbd>
|
||
+ For a keybind: <kbd>SPC h k</kbd> or <kbd>C-h k</kbd>
|
||
+ To search available keybinds: <kbd>SPC h b b</kbd> or <kbd>C-h b b</kbd>
|
||
+ Run `bin/doom doctor` to detect common issues with your development
|
||
environment and private config.
|
||
+ Check out the [FAQ] or [Discourse FAQs][discourse-faq], in case your question
|
||
has already been answered.
|
||
+ Search [Doom's issue tracker](https://github.com/doomemacs/doomemacs/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.
|
||
|
||
|
||
# Contribute
|
||
[](http://makeapullrequest.com)
|
||
[](https://github.com/bbatsov/emacs-lisp-style-guide)
|
||
[][liberapay]
|
||
[][paypal]
|
||
|
||
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!
|
||
|
||
+ I :heart: pull requests and bug reports (see the [Contributing
|
||
Guidelines][contribute])!
|
||
+ Don't hesitate to [tell me my Elisp-fu
|
||
sucks](https://github.com/doomemacs/doomemacs/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.
|
||
|
||
|
||
[contribute]: docs/contributing.org
|
||
[discord]: https://doomemacs.org/discord
|
||
[discourse]: https://discourse.doomemacs.org
|
||
[discourse-faq]: https://discourse.doomemacs.org/tag/faq
|
||
[documentation]: docs/index.org
|
||
[faq]: https://github.com/hlissner/doom-emacs/blob/master/docs/faq.org
|
||
[getting-started]: docs/getting_started.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]: https://github.com/doomemacs/doomemacs/tree/screenshots#emacsd-screenshots
|
||
|
||
[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
|
||
[eglot]: https://github.com/joaotavora/eglot
|
||
[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/radian-software/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
|
||
|
||
[liberapay]: https://liberapay.com/hlissner/donate
|
||
[paypal]: https://paypal.me/henriklissner/10
|