Emacs — 6 трюков для продуктивной работы
Чтобы начать
tl; dr: Особо нетерпеливые этот раздел могут пропускать и сразу переходить к настройкам Helm.
У меня установлен Emacs — 26.1, собранный из исходников. Вам это не потребуется. Все пакеты установятся из пакетного менеджера Emacs. Запускаете:
Вы увидите список доступных пакетов в MELPA. Не переживайте, если не слышали о таком, это что-то вроде хранилища всех пакетов дополнений, как в репозитории Debian в дистрибутивах Debian/Ubuntu. Таким образом, мы имеем длинный список доступных пакетов, как на гифке:
Если выбрать пакет, появится новый экран с коротким описанием. Обычно он содержит инструкцию для быстрого старта. Можете просто нажать i, затем x, чтобы установить пакет. Так можно поступить и с представленными ниже пакетами.
«Helm — это Emacs-фреймворк, инкрементальный поиск и автодополнение для файловых имен, имён буферов и прочих действий, требующих выбора элемента из списка возможных вариантов»
Evil Mode
EVIL расшифровывается как Еxtensible VI Layer для Emacs. Это, очевидно, большая спорная тема, отходящая от сценария использования Emacs пользователем-пуристом. Честно говоря, такого сценария нет. По-моему, сила Emacs, в основном, происходит от возможности превратить его во что угодно. Я вырос, когда не было ничего, кроме vi, использовался он мной совсем немного, но я неплохо справлялся.
«Одобрено вашим ортопедом»
Пользуясь Emacs, я регулярно пропускал командные клавиши, а все из-за того, что печатаю я ужасно медленно, по крайней мере в сравнении с реальными мастерами, с которыми я встречался.
Активируем Evil Mode:
Helm-Projectile
Не понимаю, почему люди до сих пор не бегают по улице, схватившись за голову и обезумев от радости — именно это я испытываю, используя Helm-Projectile. Гитхаб
Doom-themes
Здесь речь пойдёт об эстетике, а это вещь субъективная. Так что если Вас и так все устраивает — листайте дальше, но если Вы впечатлены изображениями выше, то эта информация для Вас.
Doom Themes помогли мне сделать внешний вид редактора современнее. Время от времени цвета навевали на меня тоску (минутка психоанализа), потому я начал искать«ту самую тему» для Emacs. Я долго пользоваться zenburn, но потом осознал, что мне действительно нравится контрастный шрифт, но чуть менее кричащий и резкий. Обратите внимание на Doom Themes, в особенности на doom-molokai, которая очень напоминает современную Atom IDE. Минимальная необходимая конфигурация представлена ниже. Я пользуюсь её модифицированной версией, которую стащил с просторов Интернета.
Rtags
Напомню, что уже писал пару постов о rtags: здесь и там.
Чтение почты в Emacs с MU4E
Заслуживает отдельного поста, так как требует нетривиальной конфигурации. По крайней мере, в моем случае. Недостаток почтовых клиентов для Emacs меня сильно огорчал в своё время (Gnus, прости). По-видимому, я не был в этом одинок, и кто-то ещё, к счастью, более сообразительный и опытный чем я, восполнил этот пробел. mu4e, наряду с offlineimap стали для меня решением для написания писем в редакторе, которое радует меня и по сей день.
ONE DUDE`S BLOG
Про Emacs.
Думаю если ты попал на эту статью, у тебя уже есть определенные представления про Emacs, можешь смело мотать ниже к конфигам и скринам :).
Но если ты вдруг не слышал про emacs
За настройку плагинов, отвечает Elisp, для любителей функционального программирования это может оказаться плюсом, лично мне данный язык неочень понравился, достаточно аляписто выглядит и тяжело читается (возможно это дело привычки).
Почему doom emacs?
Долгое время я использовал vim, а затем мигрировал на neovim. В целом меня все устраивало, из недостатков (прошу заметить, весьма субъективных), я могу отметить следующее:
Зачастую не самый удобный дебаг (существуют плагины, позволяющие отлаживать код..но не всегда все происходит бесшвно и гладко)
Не самая удобная интеграция с гитом (существует проект neogit, но он только развивается)
На этом на самом деле все :). По факту, у vim не так много недостатков, мигрировал я в общем-то не из-за них, скорее из-за преимуществ емакса.
Собственно сами преимущества:
Лучший гит клиент ever. Magit.
Он настолько удобен, что прямо сейчас, я пишу эту статью в нем. А также, я написал расширение, которое позволяет снхронизировать файлы орг с блогом.
Также в doom emacs из коробки идет поддержка vim key binding, c помощью плагина evil.
К недостаткам можно отнести более медленный запуск (зависит от прямоты рук, в моем случае запуск емакс составляет около 6-7 секунд на osx и около 2-3 секунд на arch linux). 2 Моментом является порог входа, на emacs я потратил куда больше времени и сил чем на настройку vim.
Установка doom emacs.
Для начала посетим страницу с описанием пошаговой установки emacs + doom для твоей ос. Я рассмотрю процедуру установки для osx с оптимальным клиентом.
Добавим репозиторий с emacs-plus и установим его. Путем проб и ошибок могу сказать что он наиболее оптимизирован для osx и меньше лагает, к тому же поддерживает клиент без title bar
Установим фреймворк doom
В целом, на этом этапе, у нас уже есть рабочий клиент doom emacs с первоначальными настройками.
Doom emacs что это
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. 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:
Check out the FAQ for answers to common questions about the project.
Doom is comprised of
150 optional modules, some of which may have additional dependencies. Visit their documentation or run bin/doom doctor to check for any that you may have missed.
Then read our Getting Started guide to be walked through installing, configuring and maintaining Doom Emacs.
It’s a good idea to add
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:
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 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!
About
An Emacs framework for the stubborn martian hacker
Doom emacs что это
Getting Started Guide
GNU Emacs is one grand ol’ adventure, let alone Doom Emacs. Before you start you’ll need to set up Emacs, Doom, and its packages, then learn how to take care of your new puppy/operating system. This guide will walk you through installing, using, configuring and troubleshooting all of these things, to smooth you into your Emacs journey.
This guide will gloss over many technicalities so you can get up and running as soon as possible. A more technical user manual is in the works for aspiring contributors who want a deeper understanding of how Doom Emacs works.
If you feel like we’ve missed something, join us on our Discord server and let us know!
This is what you’ll have installed by the end of this section:
These packages ought to be available through the package managers of your operating system; i.e. homebrew & macports on macOS, scoop/chocolatey on Windows, or pacman/aptitude/etc on the various Linux distributions.
Installation instructions for Emacs 27.1+ are listed below for many popular Linux distributions. In the unusual case that 27.1 or newer is unavailable on your system, you’ll have to build it from source instead.
Emacs 27.x is not available through Ubuntu’s package manager out-of-the-box, but is available through a PPA:
In some cases, you may need to delete old version of emacs and it’s dependencies first, before installing emacs27:
Then install Doom’s other dependencies:
The above installs Emacs 27 (at the time of writing).
Installing Emacs 28+ will require nix-community/emacs-overlay:
Emacs can be installed from the package list, or manually via zypper.
For example, to install on openSUSE Leap 15.1 (requires root):
If you already have an older version of Emacs installed, you will be prompted to install the update candidate (Emacs 27.1).
Download ripgrep 11.0.2 from the package list or installed manually (requires root).
Only ripgrep 0.8.1 is officially available on Leap 15.1 and 15.2, so you will need to install Rust to build ripgrep from source. Rust can be downloaded from the package list or installed manually via zypper (requires root), e.g.
See the ripgrep documentation for instructions on building from source.
Everything you need is in Gentoo’s official ::gentoo repository.
To use Emacs graphically, enable the gui USE flag. And enable the xft USE flag to render fonts correctly (see issue #4876)
To install the latest unmasked version compatible with Doom:
Or, for GCCEmacs/Native Compilation, use the live ebuild for version 28.0 with the jit USE flag:
Unmask the desired ebuild by adding the following to package.accept_keywords :
Add the jit USE flag to package.use :
MacOS users have many options for installing Emacs, but not all of them are well suited to Doom. Before we get to that you’ll need either the Homebrew or MacPorts package manager installed (you only need one):
First, Doom’s dependencies:
For Emacs itself, these three formulas are the best options, ordered from most to least recommended for Doom (based on compatibility).
Where not to install Emacs from
These builds/forks have known compatibility issues with Doom and are very likely to cause issues later on. They are not recommended:
There are four ports (at time of writing) available through MacPorts, and they are all acceptable options:
Or by replacing /usr/local/bin/emacs with a shim script containing:
WARNING: Emacs on Windows is much slower than its Linux or macOS counterparts. There are some suggestions on how to speed it up later in this section.
There are three methods for installing Emacs 27.x on Windows, each with their pros and cons:
If you don’t know which to choose, I highly recommend WSL; it produces the fastest and most stable environment of the three, but has the most complex installation process.
Before moving on to installing Emacs et co, a few steps to prepare Windows for Emacs are necessary:
This way, you don’t have to type all of C:\Users\USERNAME\.emacs.d\bin\doom every time you need to run this script (and you’ll need to, often).
Now we’re ready to move on!
Chocolatey is a package manager for Windows, and is the simplest way to install Emacs and Doom’s dependencies:
Scoop will work too, but because Emacs is a GUI application you’ll need to enable the ‘extras’ Scoop bucket:
With a precompiled binary + Git Bash
(Credit goes to @earvingad and his fantastic tutorial for informing this guide)
And done! Keep git-bash.exe open, you’ll need it for the rest of this guide.
IMPORTANT: you’ll need to open git-bash.exe whenever you want to run a bin/doom command.
With WSL + Ubuntu 18.04 LTS
(Credit goes to @lunias and https://ethanaa.com/blog/switching-to-doom-emacs/#installing-on-windows-10 “>his fantastic tutorial for informing this guide)
And done! Keep Ubuntu open, you’ll need it for the rest of this guide.
With Emacs and Doom’s dependencies installed, next is to install Doom Emacs itself:
doom install will set up your DOOMDIR at
/.doom.d (if it doesn’t already exist) and will work you through the first-time setup of Doom Emacs. Carefully follow any instructions it puts out.
The bin/doom utility
This utility is your new best friend. It won’t spot you a beer, but it’ll shoulder much of the work associated with managing and maintaining your Doom Emacs configuration, and then some. Not least of which is installation of and updating Doom and your installed packages.
It exposes a variety of commands. bin/doom help will list them all, but here is a summary of the most important ones:
Install Doom Manually
To understand the purpose of the
/.doom.d directory and
/.doom.d/init.el file, see the Configure section further below.
Install Doom alongside other configs (with Chemacs2)
Chemacs2 is a bootloader for Emacs. It allows you to switch between multiple Emacs configurations. Here is a quick guide for setting it up with Doom Emacs as the default config:
If no profile is specified, the default profile is used.
The Module Index lists all Doom’s available modules, with links to their documentation. Documentation is a work-in-progrees; some modules may not have README.org files yet!
Use M-x doom/help-modules (bound to SPC h d m or C-h d m ) to jump to a module’s documentation from within Doom, otherwise, place your cursor on a module in your doom! block (in
/.doom.d/init.el ) and press K to jump to its documentation (or gd to jump to its source code). C-c g k and C-c g d for non-evil users, respectively.
Doom is an active project and many of its 300+ packages are in active development as well. It is wise to occasionally update:
If you want to update Doom manually, doom upgrade is equivalent to:
To upgrade only your packages (and not Doom itself):
To minimize issues while upgrading, avoid modifying Doom’s source files in
/.doom.d ). Read the Configure section for more on configuring Doom.
The bin/doom script doesn’t currently offer rollback support for Doom or its packages (yet).
If you’re here from another Emacs distribution (or your own), here are a few things to be aware of while you convert your old config to Doom:
/.doom.d/packages.el to install your packages.
See “Package Management”, further in this guide.
(This section is incomplete)
From vanilla Emacs
Have you migrated from your own config? Help me flesh out this section by letting me know what kind of hurdles you faced in doing so. You’ll find me on our Discord server.
Have you migrated from Spacemacs? Help me flesh out this section by letting me know what kind of hurdles you faced in doing so. You’ll find me on our Discord server.
Change the DOOMDIR environment variable to change where Doom looks for this directory. Symlinks will work as well.
init.el Where you’ll find your doom! block, which controls what Doom modules are enabled and in what order they will be loaded.
This file is evaluated early when Emacs is starting up; before any other module has loaded. You generally shouldn’t add code to this file unless you’re targeting Doom’s CLI or something that needs to be configured very early in the startup process.
config.el Here is where 99.99% of your private configuration should go. Anything in here is evaluated after all other modules have loaded, when starting up Emacs. packages.el Package management is done from this file; where you’ll declare what packages to install and where from.
Note: do not use M-x customize or the customize API in general. Doom is designed to be configured programmatically from your config.el, which can conflict with Customize’s way of modifying variables.
If you’re concerned about defcustom setters, Doom has a setq! macro that will trigger them.
Your doom! block should look something like this:
It controls what modules are enabled and in what order they are loaded. Some modules have optional features that can be enabled by passing them flags, denoted by a plus prefix:
Different modules support different flags. You’ll find a comprehensive list of available modules and their supported flags in Module Index. Flags that a module does not recognize will be silently ignored.
IMPORTANT: any changes to your doom! block won’t take effect until you run doom sync on the command line.
doom doctor will detect issues with your doom! block, such as duplicate or misspelled modules and flags.
**Doom Emacs does not use package.el** (the package manager built into Emacs). Instead, it uses its own declarative package manager built on top of straight.el.
Packages are declared in packages.el files. You’ll find one in your DOOMDIR and in many of Doom’s modules. Read on to learn how to use this system to install your own packages.
WARNING: If you’re here from another Emacs distro (or vanilla Emacs), be wary of the :ensure property in use-package blocks, because it will attempt (and fail) to install packages through package.el. Tutorials will recommend you install packages this way too!
To install a package, add a package! declaration for it to DOOMDIR/packages.el :
If a package could not be found in any known repo you will get an error like:
Could not find package X in recipe repositories: (org-elpa melpa gnu-elpa-mirror emacsmirror-mirror)
The most likely cause for this is either:
package! will return non-nil if the package is cleared for install and hasn’t been disabled elsewhere. Use this fact to chain package dependencies together. e.g.
Installing packages from external sources
To install a package straight from an external source (like github, gitlab, etc), you’ll need to specify a MELPA-style straight recipe:
Here are a few examples:
The specification for the package! macro’s :recipe is laid out in Straight.el’s README.
IMPORTANT: Run bin/doom sync whenever you modify packages.el files to ensure your changes take effect.
Pinning packages to specific commits
All of Doom’s packages are pinned by default. A pinned package is a package locked to a specific commit, like so:
To unpin a package, use the unpin! macro:
Though it is highly discouraged, you may unpin all packages and make Doom Emacs rolling release:
Unpinning all packages is discouraged because Doom’s modules are designed against the pinned versions of its packages. More volatile packages (like lsp-mode, ein and org) change rapidly, and are likely to cause breakages if unpinned.
Instead, it’s a better to selectively unpin packages, or repin them to the exact commit you want.
The package! macro possesses a :disable property:
There is also the disable-packages! macro for conveniently disabling multiple packages:
IMPORTANT: Run bin/doom sync whenever you modify packages.el files to ensure your changes take effect.
Changing a recipe for an included package
To install a package only if a built-in package doesn’t exist, use :built-in ‘prefer :
Using/loading local packages
Say you are developing an Emacs package locally and want to “install” it for live testing. To do this specify a :local-repo in that package’s recipe:
IMPORTANT: Remember to run doom sync to rebuild your package after you’ve changed it, and to re-index any autoloads in it.
For more flexibility, the use-package-hook! is another option, but should be considered a last resort (because there is usually a better way). It allows you to disable, append/prepend to and/or overwrite Doom’s use-package! blocks. These are powered by use-package ’s inject-hooks under the hood.
use-package-hook! must be used before that package’s
block. Therefore it must be used from your private init.el file.
Reloading your config
You may find it helpful to have your changes take effect immediately. For things that don’t require a complete restart of Doom Emacs (like changing your enabled modules or installed packages), you can evaluate Emacs Lisp code on-the-fly.
gr works for most languages, but using it on Elisp is a special case; it’s executed within your current session of Emacs. You can use this to modify Emacs’ state on the fly.
While all this is helpful for reconfiguring your running Emacs session, it can also be helpful for debugging.
Writing your own modules
To create your own module you need only create a directory for it in
/.doom.d/init.el to enable it.
If a private module possesses the same name as a built-in Doom module (say, :lang org ), it replaces the built-in module. Use this fact to rewrite modules you don’t agree with.
Of course, an empty module isn’t terribly useful, but it goes to show that nothing in a module is required. The typical module will have:
These are a few exceptional examples of a well-rounded module:
The remainder of this guide will go over the technical details of a Doom module.
Doom recognizes a handful of special file names, none of which are required for a module to function. They are:
This file is loaded early, before anything else, but after Doom core is loaded. It is loaded in both interactive and non-interactive sessions (it’s the only file, besides cli.el that is loaded when the bin/doom starts up).
The heart of every module. Code in this file should expect dependencies (in packages.el ) to be installed and available. Use it to load and configure its packages.
This file is where package declarations belong. It’s also a good place to look if you want to see what packages a module manages (and where they are installed from).
The ”Package Management” section goes over the package! macro and how to deal with packages.
autoload/*.el OR autoload.el
These files are where you’ll store functions that shouldn’t be loaded until they’re needed and logic that should be autoloaded (evaluated very, very early at startup).
For example, the :lang cc module’s doctor checks to see if the irony server is installed:
This file is read when bin/doom starts up. Use it to define your own CLI commands or reconfigure existing ones.
Doom’s unit tests go here. More information on them to come…
These can be loaded with the load! macro, which will load an elisp file relative to the file it’s used from. e.g.
This can be useful for splitting up your configuration into multiple files, saving you the hassle of creating multiple modules.
A module’s files have a precise load-order, which differs slightly depending on what kind of session it is. Doom has three types of sessions:
Interactive session the typical session you open when you intend to use Emacs (e.g. for text editing). This loads the most, because you will likely be using a lot of it. Batch session this is a non-interactive session, loaded when you execute Emacs commands on the command line with no UI, e.g.
emacs –batch –eval ‘(message “Hello world”)’
The expectation for these sessions is that it should quickly spin up, run the command then quit, therefore very little is loaded in this session.
CLI session this is the same as a batch session except it is what starts up when you run any bin/doom command.
With that out of the way, here is the load order of Doom’s most important files:
| File | Interactive | Batch | CLI |
|---|---|---|---|
| yes | no | no | |
| yes | no | no | |
| $DOOMDIR/init.el | yes | yes | yes |
| < /.emacs.d,$DOOMDIR>/modules/*/*/init.el | yes | yes | yes |
| $DOOMDIR/cli.el | no | no | yes |
| < /.emacs.d,$DOOMDIR>/modules/*/*/cli.el | no | no | yes |
| < /.emacs.d,$DOOMDIR>/modules/*/*/config.el | yes | no | no |
| $DOOMDIR/config.el | yes | no | no |
A module may choose to interpret flags however it wishes, and can be tested for using the featurep! macro:
Use this fact to make aspects of a module conditional. e.g. Prevent company plugins from loading if the :completion company module isn’t enabled.
Autoload cookies were mentioned earlier. A couple more exist that are specific to Doom Emacs. This section will go over what they do and how to use them.
Any file in a module can have a ;;;###if FORM cookie at or near the top of the file (must be within the first 256 bytes of the file). FORM is evaluated to determine whether or not to include this file for autoloads scanning (on doom sync ) or byte-compilation (on doom compile ).
Use this to prevent errors that would occur if certain conditions aren’t met. For example, say file.el is using a certain function that won’t be available if the containing module wasn’t enabled with a particular flag. We could safe guard against this with:
This will prevent errors at compile time or if/when that file is loaded.
Another example, this time contingent on so-long not being present:
Keep in mind that FORM runs in a limited, non-interactive sub-session. I don’t recommend doing anything expensive or especially complicated in them.
This cookie exists solely to assist the doom/help-packages command. This command shows you documentation about packages in the Emacs ecosystem, including the ones that are installed. It also lists a) all the modules that install said package and b) all the places it is configured.
It accomplishes A by scanning for at package! declarations for that package, but it accomplishes B by scanning for:
Use it to let doom/help-packages know where to find config for packages where no after! or use-package! call is involved.
An autodef is a special kind of autoloaded function (or macro) which Doom guarantees will always be defined, whether or not its containing module is enabled (but will no-op if it is disabled).
If the containing module is disabled the definition is replaced with a macro that does not process its arguments, so it is a zero-cost abstraction.
You can browse the available autodefs in your current session with M-x doom/help-autodefs ( SPC h d u or C-h d u ).
An autodef cookie is used in exactly the same way as the autoload cookie:
An example would be the set-company-backend! function that the :completion company module exposes. It lets you register company completion backends with certain major modes. For instance:
And if :completion company is disabled, this call and its arguments are left unprocessed and ignored.
Common mistakes when configuring Doom Emacs
Having helped many users configure Doom, I’ve spotted a few recurring oversights that I will list here, in the hopes that it will help you avoid the same mistakes:
Packages are eagerly loaded
Using use-package! without a deferring keyword (one of: :defer :after :commands :defer-incrementally :after-call ) will load the package immediately. This causes other packages to be pulled in and loaded, which will compromise many of Doom’s startup optimizations.
This is usually by accident. Choosing which keyword to use depends on the needs of the package, so there is no simple answer to this.
Manual package management
A lot of Emacs documentation and help will contain advice to install packages with package.el’s API (e.g. package-install ) or with use-package’s :ensure keyword). You are free to do this, if it is your preference, but otherwise, Doom has its own package management system.
Migrating use-package code to Doom is usually a case of removing the :ensure keyword and adding a (package! PACKAGENAME) to
/.doom.d/packages.el (and running doom sync to sync your config).
Using org-babel-do-load-languages to load your babel packages
There may be some special cases, however. Doom tries to handle a couple of them (e.g. with ob-jupyter, ob-ipython and ob-async). If you are experiencing errors while trying to use a certain language in org src blocks, check out the :lang org module documentation for details on how to add support for it.
Using delete-trailing-whitespaces or whitespace-cleanup to manage leftover whitespace
These two lines are a common sight in Emacs configs, but they are unnecessary for Doom Emacs. We already use the more sophisticated ws-butler to manage extraneous whitespace. However, you might have the impression that it isn’t working. That’s because ws-butler works in two unusual ways, meant to be less imposing than its alternatives:
Why do this? Because I believe file-wide reformatting should be a deliberate act (and not blindly automated). If it is necessary, chances are you’re working on somebody else’s project – or with other people, but here, large scale whitespace changes could cause problems or simply be rude. We don’t endorse PRs that are 1% contribution and 99% whitespace!
Why do this? Because you might have wanted to use that space for something in your current editing session, and it would be inconvenient for the editor to delete it before you got to it.
If you use it, it’s there. If you don’t, it isn’t written to the file.
When problems arise, you should be prepared to collect information in order to solve them, or for the bug report you’re about to write. Both Emacs and Doom provide tools to make this easier. Here are a few things you can try, first:
If none of these things have helped you, then it’s time to open a bug report. See ”Reporting Issues” in the contributing guidelines on how to file an effective bug report.
Looking up documentation and state from within Emacs
Variables, functions, faces, etc.
Emacs is a Lisp interpreter whose state you can access on-the-fly with tools provided to you by Emacs itself. They’re available on the SPC h prefix by default. Use them to debug your sessions.
Here are some of the more important ones:
You can also evaluate code with eval-expression ( M-; or SPC ; ).
For Doom Modules, packages, autodefs, etc.
How to extract a backtrace from an error
If you encounter an error while using Doom Emacs, you’re probably about to head off and file a bug report (or request help on our Discord server). Before you do, please generate a backtrace to include with it.
To do so you must enable debug-on-error then recreate the error.
There are three ways to enable debug-on-error :
Now that debug-on-error is on, recreate the error. A window should pop up with a backtrace.
A backtrace from bin/doom
Evaluating Elisp on-the-fly
Often, you may find it helpful for debugging to evaluate some Emacs Lisp. Here are couple things you can do:
How to determine the origin of a bug
Testing in Doom’s sandbox
“The sandbox” is one of Doom Emacs’ features; it is a test bed for running elisp in a fresh instance of Emacs with varying amounts of Doom loaded (none at all, all of it, or somewhere in between). This can be helpful for isolating bugs to determine who you should report a bug to.
If you can recreate a bug in vanilla Emacs then it should be reported to the developers of the relevant packages or, perhaps, the Emacs devs themselves.
Otherwise, it is best to bring it up on the Doom Emacs issue list, rather than confusing and inundating the Emacs community with Doom-specific issues.
Opening the sandbox
There are three common ways to access the sandbox:
Doing any of the above will pop up a *doom:sandbox* window. What you enter into this buffer will be executed in the new instance of Emacs when you decide to launch it.
Launching the sandbox
You have four options when it comes to launching the sandbox:
C-c C-c This launches “vanilla Emacs”. Vanilla means nothing is loaded; purely Emacs and nothing else. If you can reproduce an error here, then the issue likely lies in the plugin(s) you are testing or in Emacs itself. C-c C-d This launches “vanilla Doom”, which is vanilla Emacs plus Doom’s core. This does not load your private config, nor any of Doom’s (or your) modules. C-c C-p This launches “vanilla Doom+”. That is, Doom core plus the modules that you have specified in the doom! block of your private config (in
/.doom.d/init.el ). This does not load your private config, however. C-c C-f This launches “full Doom”. It loads Doom’s core, your enabled modules, and your private config. This instance should be identical to the instance you launched it from.
All new instances will inherit your load-path so you can access any packages you have installed.
