diff --git a/docs/contributing.org b/docs/contributing.org deleted file mode 100644 index 7d3d38dcd..000000000 --- a/docs/contributing.org +++ /dev/null @@ -1,167 +0,0 @@ -#+TITLE: Contributing -#+STARTUP: nofold - -Doom Emacs is an active and ongoing project, maintained mostly by a single -person, but includes the efforts of 200 contributors and growing. There is no -shortage of things that need doing; bugs that need stomping, features that need -implementing, and documentation that needs documenting. If Doom's been useful to -you, convert some caffiene into code; it'd be a huge help! - -You are welcome to [[https://discord.gg/qvGgnVx][join us on our Discord server]], otherwise read on to learn how -to contribute to our fine corner of the interwebs. - -* Table of Contents :TOC_3: -- [[#where-can-i-help][Where can I help?]] -- [[#reporting-issues][Reporting issues]] - - [[#acquire-a-backtrace-from-errors][Acquire a backtrace from errors]] - - [[#create-a-step-by-step-reproduction-guide][Create a step-by-step reproduction guide]] - - [[#include-information-about-your-doom-install][Include information about your Doom install]] - - [[#debugging-crashes-with-gdb][Debugging crashes with gdb]] -- [[#suggesting-features-keybinds-andor-enhancements][Suggesting features, keybinds and/or enhancements]] -- [[#contributing-code][Contributing code]] - - [[#conventions][Conventions]] - - [[#code-style][Code style]] - - [[#naming-conventions][Naming conventions]] - - [[#commits--prs][Commits & PRs]] - - [[#keybind-conventions][Keybind conventions]] - - [[#your-first-code-contribution][Your first code contribution]] - - [[#submitting-pull-requests][Submitting pull requests]] - - [[#contributing-to-doom-core][Contributing to Doom core]] - - [[#contributing-to-an-existing-module][Contributing to an existing module]] - - [[#contributing-a-new-module][Contributing a new module]] -- [[#contributing-documentation][Contributing documentation]] - - [[#contributing-to-dooms-manual][Contributing to Doom's manual]] - - [[#contributing-module-documentation][Contributing module documentation]] -- [[#help-keep-packages-up-to-date][Help keep packages up-to-date!]] -- [[#other-ways-to-support-doom-emacs][Other ways to support Doom Emacs]] -- [[#special-thanks][Special thanks]] - -* Where can I help? -+ Our [[https://github.com/hlissner/doom-emacs/issues][issue tracker]] has many issues. If you find one that you have an answer to, - it would be a huge help! -+ Look for issues tagged [[https://github.com/hlissner/doom-emacs/labels/good%20first%20issue][good first issue]]. These were judged to have a low - barrier of entry. -+ Look for issues tagged [[https://github.com/hlissner/doom-emacs/labels/help%20wanted][help wanted]]. These tend to be a little (or a lot) - harder, and are issues outside my own expertise. -+ If you've encountered a bug, [[https://github.com/hlissner/doom-emacs/issues/new/choose][file a bug report]]. -+ The [[https://github.com/hlissner/doom-emacs/projects/3][development roadmap board]] is a rough timeline of what is being worked on - and when. It will give you an idea of what will change and where you can - redirect your efforts. -+ The [[https://github.com/hlissner/doom-emacs/projects/2][plugins under review board]] lists third party plugins being considered (or - rejected) for inclusion in Doom Emacs. Approved and unclaimed packages are - open for you to implement yourself. -+ The [[https://github.com/hlissner/doom-emacs/projects/5][upstream bugs board]] lists known issues that have external causes, but - affect Doom. If you're feeling adventurous (or are better acquainted with the - cause) perhaps you can address them at the source. - -* TODO Reporting issues -You've found a problem and you're ready to fire off that bug report. Hold up! -Before you do that, [[file:getting_started.org::*Troubleshoot][have a look at our Troubleshooting guide]]. If none of these -suggestions pan out, /then/ it is time to file a bug report. - -An effective bug report is informative. Please try to provide: - -+ A backtrace of all mentioned errors. -+ A step-by-step reproduction of the issue. -+ Information about your Doom config and system environment. -+ Screenshots/casts of the issue (if possible). - -This section will show you how to collect this information. - -** Acquire a backtrace from errors -See "[[file:getting_started.org::*How to extract a backtrace from an error][How to extract a backtrace from an error]]" in the [[file:getting_started.org][Getting Started]] guide. - -** TODO Create a step-by-step reproduction guide - -** TODO Include information about your Doom install - -** TODO Debugging crashes with gdb - -* TODO Suggesting features, keybinds and/or enhancements - -* TODO Contributing code -There's much to be done around here! We need bugfixes, new features, and -documentation. If you'd like to convert some caffeine into Emacs Lisp, here are -a few considerations before starting that PR: - -** TODO Conventions -*** TODO Code style -Doom conforms to [[https://github.com/bbatsov/emacs-lisp-style-guide][@bbatsov's emacs-lisp style guide]] with the following -exceptions: - -+ Use ~mapc~ instead of ~seq-do~. -+ No hanging parentheses -+ We use =DEPRECATED= to indicate code that will eventually be removed. - -*** Naming conventions -Doom has a number of naming conventions that it uses in addition to the standard -lisp conventions. Third party packages may use their own conventions as well. - -**** Lisp Naming Conventions -The lisp conventions are simple. Symbols follow ~NAMESPACE-SYMBOLNAME~ for -public variables/functions (e.g. ~bookmark-default-file~ or -~electric-indent-mode~) and ~NAMESPACE--SYMBOLNAME~ for private ones (e.g. -~byte-compile--lexical-environment~ and ~yas--tables~). - -~NAMESPACE~ is usually the name of the containing file or package. E.g. the -~company~ plugin prefixes all its variables/functions with ~company-~. - -**** Doom Naming Conventions -+ ~doom/NAME~ or ~+MODULE/NAME~ :: Denotes a public command designed to be used - interactively, via =M-x= or a keybinding. e.g. ~doom/info~, ~+popup/other~, - ~+ivy/rg~. -+ ~doom:NAME~ :: A public evil operator, motion or command. e.g. ~+evil:align~, - ~+ivy:rg~. -+ ~doom-[-]NAME-h~ or ~+MODULE-[-]NAME-h~ :: A non-interactive function meant to - be used (exclusively) as a hook. e.g. ~+cc-fontify-constants-h~, - ~+flycheck-buffer-h~. -+ ~doom-[-]NAME-a~ or ~+MODULE-[-]NAME-a~ :: Functions designed to be used as - advice for other functions. e.g. ~doom-set-jump-a~, - ~doom--fix-broken-smie-modes-a~, ~+org--babel-lazy-load-library-a~ -+ ~doom-[-]NAME-fn~ or ~+MODULE-[-]NAME-fn~ :: Indicates an [[https://en.wikipedia.org/wiki/Strategy_pattern][strategy]] function. A - good rule of thumb for what makes a strategy function is: is it - interchangeable? Can it be replaced with another function with a matching - signature? e.g. ~+lookup-dumb-jump-backend-fn~, ~+magit-display-buffer-fn~, - ~+workspaces-set-project-action-fn~ -+ ~abc!~ :: A public Doom "autodef" function or macro. An autodef should always - be defined, even if its containing module is disabled (i.e. they will not - throw a void-function error). The purpose of this is to avoid peppering module - configs with conditionals or `after!` blocks before using their APIs. They - should noop if their module is disabled, and should be zero-cost in the case - their module is disabled. - - Autodefs usually serve to configure Doom or a module. e.g. ~after!~, - ~set-company-backends!~, ~set-evil-initial-state!~ - -*** TODO Commits & PRs -+ Target =develop= instead of =master=. The only exception are hotfixes! - -*** TODO Keybind conventions - -** TODO Your first code contribution - -** TODO Submitting pull requests - -** TODO Contributing to Doom core - -** TODO Contributing to an existing module - -** TODO Contributing a new module - -* TODO Contributing documentation -Doom Emacs' documentation is an ongoing effort. If you have suggestions, -improvements, tutorials and/or articles to submit, don't hesitate to get in -contact via our [[https://discord.gg/bcZ6P3y][Discord server]] or [[mailto:henrik@lissner.net][email]]. I appreciate any help I can get! - -** TODO Contributing to Doom's manual - -** TODO Contributing module documentation - -* TODO Help keep packages up-to-date! -Doom pins all its packages to reduce the likelihood of upstream breakage leaking -into Doom Emacs. However, we may miss when a package releases hotfixes for -critical issues. Let us know or PR a bump to our pinned packages. - -* TODO Other ways to support Doom Emacs - -* TODO Special thanks diff --git a/docs/getting_started.org b/docs/getting_started.org deleted file mode 100644 index 13980053f..000000000 --- a/docs/getting_started.org +++ /dev/null @@ -1,1677 +0,0 @@ -#+TITLE: Getting Started Guide -#+STARTUP: nofold - -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. - -#+begin_quote -If you feel like we've missed something, [[https://discord.gg/qvGgnVx][join us on our Discord server]] and let -us know! -#+end_quote - -* Table of Contents :TOC_4: -- [[#install][Install]] - - [[#emacs--dependencies][Emacs & dependencies]] - - [[#on-linux][On Linux]] - - [[#ubuntu][Ubuntu]] - - [[#fedora][Fedora]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] - - [[#opensuse][openSUSE]] - - [[#gentoo-linux][Gentoo Linux]] - - [[#on-macos][On macOS]] - - [[#with-homebrew][With Homebrew]] - - [[#with-macports][With MacPorts]] - - [[#on-windows][On Windows]] - - [[#with-chocolatey--scoop][With chocolatey / scoop]] - - [[#with-a-precompiled-binary--git-bash][With a precompiled binary + Git Bash]] - - [[#with-wsl--ubuntu-1804-lts][With WSL + Ubuntu 18.04 LTS]] - - [[#doom-emacs][Doom Emacs]] - - [[#the-bindoom-utility][The ~bin/doom~ utility]] - - [[#install-doom-manually][Install Doom Manually]] - - [[#install-doom-alongside-other-configs-with-chemacs2][Install Doom alongside other configs (with Chemacs2)]] - - [[#externalsystem-dependencies][External/system dependencies]] -- [[#update--rollback][Update & Rollback]] - - [[#rollback][Rollback]] - - [[#updowngrading-emacs][Up/Downgrading Emacs]] -- [[#migrate][Migrate]] - - [[#from-vanilla-emacs][From vanilla Emacs]] - - [[#from-spacemacs][From Spacemacs]] -- [[#configure][Configure]] - - [[#modules][Modules]] - - [[#package-management][Package management]] - - [[#installing-packages][Installing packages]] - - [[#installing-packages-from-external-sources][Installing packages from external sources]] - - [[#pinning-packages-to-specific-commits][Pinning packages to specific commits]] - - [[#disabling-packages][Disabling packages]] - - [[#changing-a-recipe-for-an-included-package][Changing a recipe for an included package]] - - [[#usingloading-local-packages][Using/loading local packages]] - - [[#configuring-doom][Configuring Doom]] - - [[#configuring-packages][Configuring packages]] - - [[#reloading-your-config][Reloading your config]] - - [[#binding-keys][Binding keys]] - - [[#writing-your-own-modules][Writing your own modules]] - - [[#file-structure][File structure]] - - [[#initel][=init.el=]] - - [[#configel][=config.el=]] - - [[#packagesel][=packages.el=]] - - [[#autoloadel-or-autoloadel][=autoload/*.el= OR =autoload.el=]] - - [[#doctorel][=doctor.el=]] - - [[#cliel][=cli.el=]] - - [[#testtest-el][=test/**/test-*.el=]] - - [[#additional-files][Additional files]] - - [[#load-order][Load order]] - - [[#flags][Flags]] - - [[#doom-cookies][Doom cookies]] - - [[#if][~;;;###if~]] - - [[#package][~;;;###package~]] - - [[#autodef][~;;;###autodef~]] - - [[#common-mistakes-when-configuring-doom-emacs][Common mistakes when configuring Doom Emacs]] - - [[#packages-are-eagerly-loaded][Packages are eagerly loaded]] - - [[#manual-package-management][Manual package management]] - - [[#using-org-babel-do-load-languages-to-load-your-babel-packages][Using ~org-babel-do-load-languages~ to load your babel packages]] - - [[#using-delete-trailing-whitespaces-or-whitespace-cleanup-to-manage-leftover-whitespace][Using ~delete-trailing-whitespaces~ or ~whitespace-cleanup~ to manage leftover whitespace]] -- [[#troubleshoot][Troubleshoot]] - - [[#looking-up-documentation-and-state-from-within-emacs][Looking up documentation and state from within Emacs]] - - [[#variables-functions-faces-etc][Variables, functions, faces, etc.]] - - [[#for-doom-modules-packages-autodefs-etc][For Doom Modules, packages, autodefs, etc.]] - - [[#how-to-extract-a-backtrace-from-an-error][How to extract a backtrace from an error]] - - [[#enabling-debug-on-error][Enabling ~debug-on-error~]] - - [[#a-backtrace-from-bindoom][A backtrace from ~bin/doom~]] - - [[#evaluating-elisp-on-the-fly][Evaluating Elisp on-the-fly]] - - [[#how-to-determine-the-origin-of-a-bug][How to determine the origin of a bug]] - - [[#testing-in-dooms-sandbox][Testing in Doom's sandbox]] - - [[#opening-the-sandbox][Opening the sandbox]] - - [[#launching-the-sandbox][Launching the sandbox]] - - [[#testing-packages-in-the-sandbox][Testing packages in the sandbox]] - - [[#bisecting-your-private-config][Bisecting your private config]] - - [[#bisecting-doom-emacs][Bisecting Doom Emacs]] - -* Install -This is what you'll have installed by the end of this section: - -- Git 2.23+ -- Emacs 27.1+ *(27.2 is recommended, or [[https://www.emacswiki.org/emacs/GccEmacs][native-comp]])* -- [[https://github.com/BurntSushi/ripgrep][ripgrep]] 11.0+ -- GNU Find -- (Optional) [[https://github.com/sharkdp/fd][fd]] 7.3.0+ (known as ~fd-find~ on Debian, Ubuntu & derivatives) -- - improves performance for many file indexing commands - -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. - -** Emacs & dependencies -*** On Linux -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 [[https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html][build it from source]] instead. - -**** Ubuntu -Emacs 27.x is not available through Ubuntu's package manager out-of-the-box, but -is available through a PPA: - -#+BEGIN_SRC bash -add-apt-repository ppa:kelleyk/emacs -apt-get update -apt-get install emacs27 -#+END_SRC - -Or through snap: - -#+BEGIN_SRC bash -snap install emacs --classic -#+END_SRC - -In some cases, you may need to delete old version of emacs and it's dependencies first, before installing emacs27: -#+BEGIN_SRC bash -sudo apt remove emacs -sudo apt autoremove -#+END_SRC - -***** Other dependencies -Then install Doom's other dependencies: -#+BEGIN_SRC bash -apt-get install ripgrep fd-find - -# On 18.04 or older, ripgrep and fd-find won't be available in -# official repos. You'll need to install them another way, e.g. -sudo dpkg -i fd_8.2.1_amd64.deb # adapt version number and architecture -sudo dpkg -i fd_8.2.1_amd64.deb # adapt version number and architecture -#+END_SRC - -**** Fedora -#+BEGIN_SRC bash -# required dependencies -dnf install emacs git ripgrep -# optional dependencies -dnf install fd-find # is 'fd' in Fedora <28 -#+END_SRC - -**** Arch Linux -#+BEGIN_SRC bash -# required dependencies -pacman -S git emacs ripgrep -# optional dependencies -pacman -S fd -#+END_SRC - -The above installs Emacs 27 (at the time of writing). - -**** NixOS -On NixOS Emacs 27.2 can be installed via ~nix-env -Ai nixos.emacs~, or -permanently with the following added to ~etc/nixos/configuration.nix~: - -#+BEGIN_SRC nix -environment.systemPackages = with pkgs; [ - # required dependencies - git - emacs # Emacs 27.2 - ripgrep - # optional dependencies - coreutils # basic GNU utilities - fd - clang -]; -#+END_SRC - -Installing Emacs 28+ will require [[https://github.com/nix-community/emacs-overlay/issues][nix-community/emacs-overlay]]: -#+BEGIN_SRC nix -nixpkgs.overlays = [ - (import (builtins.fetchTarball https://github.com/nix-community/emacs-overlay/archive/master.tar.gz)) -]; - -environment.systemPackages = [ - pkgs.emacsGcc # Installs Emacs 28 + native-comp -]; -#+END_SRC - -**** openSUSE -***** Emacs 27.1 -Emacs can be installed from the [[https://software.opensuse.org/download.html?project=editors&package=emacs][package list]], or manually via zypper. - -For example, to install on openSUSE Leap 15.1 (requires root): -#+BEGIN_SRC bash -zypper addrepo https://download.opensuse.org/repositories/editors/openSUSE_Leap_15.1/editors.repo -zypper refresh -zypper install emacs -#+END_SRC - -If you already have an older version of Emacs installed, you will be prompted to -install the update candidate (Emacs 27.1). - -***** ripgrep -Download ripgrep 11.0.2 from [[https://software.opensuse.org/download/package?package=ripgrep&project=openSUSE%3AFactory][the package list]] or installed manually (requires -root). -#+BEGIN_SRC bash -zypper addrepo https://download.opensuse.org/repositories/openSUSE:Factory/standard/openSUSE:Factory.repo -zypper refresh -zypper install ripgrep -#+END_SRC - -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 [[https://software.opensuse.org/package/rust][from -the package list]] or installed manually via zypper (requires root), e.g. -#+BEGIN_SRC bash -zypper addrepo https://download.opensuse.org/repositories/openSUSE:Leap:15.1:Update/standard/openSUSE:Leap:15.1:Update.repo -zypper refresh -zypper install rust -#+END_SRC - -See the [[https://github.com/BurntSushi/ripgrep#building][ripgrep documentation]] for instructions on building from source. - -**** Gentoo Linux -Everything you need is in Gentoo's official =::gentoo= repository. - -***** Emacs -To use Emacs graphically, enable the =gui= USE flag. And enable the =xft= USE flag to render fonts correctly (see -[[https://github.com/hlissner/doom-emacs/issues/4876][issue #4876]]) -#+begin_src sh -echo "app-editors/emacs gui xft" >> /etc/portage/package.use/emacs -#+end_src - -To install the latest unmasked version compatible with Doom: -#+begin_src sh -emerge '>=app-editors/emacs-27.0' -#+end_src - -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=: -#+begin_src -=app-editors/emacs-28.0.9999 ** -#+end_src - -Add the =jit= USE flag to =package.use=: -#+begin_src -=app-editors/emacs-28.0.9999 jit -#+end_src - -And emerge: -#+begin_src sh -emerge =app-editors/emacs-28.0.9999 -#+end_src - -***** Other Dependencies -#+begin_src sh -# required -emerge '>=dev-vcs/git-2.23' '>=sys-apps/ripgrep-11.0' sys-apps/findutils -# optional -emerge '>=sys-apps/fd-7.3.0' -#+end_src - -*** On macOS -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): - -+ [[http://brew.sh/][How to install Homebrew]] -+ [[https://www.macports.org/install.php][How to install MacPorts]] - -**** With Homebrew -First, Doom's dependencies: -#+BEGIN_SRC bash -# required dependencies -brew install git ripgrep -# optional dependencies -brew install coreutils fd -# Installs clang -xcode-select --install -#+END_SRC - -For Emacs itself, these three formulas are the best options, ordered from most -to least recommended for Doom (based on compatibility). - -- [[https://bitbucket.org/mituharu/emacs-mac/overview][emacs-mac]]. It offers good integration - with macOS, native emojis and better childframe support. - #+BEGIN_SRC bash - brew tap railwaycat/emacsmacport - brew install emacs-mac --with-modules - ln -s /usr/local/opt/emacs-mac/Emacs.app /Applications/Emacs.app - #+END_SRC - -- [[https://github.com/d12frosted/homebrew-emacs-plus][emacs-plus]]. Some users have - experienced [flashing artifacts when scrolling](https://github.com/d12frosted/homebrew-emacs-plus/issues/314): - #+BEGIN_SRC bash - brew tap d12frosted/emacs-plus - brew install emacs-plus - ln -s /usr/local/opt/emacs-plus/Emacs.app /Applications/Emacs.app - #+END_SRC - -- [[https://formulae.brew.sh/formula/emacs][emacs]] is another acceptable option, **but does not provide a Emacs.app**: - #+BEGIN_SRC bash - brew install emacs - #+END_SRC - -***** 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: - -+ emacsformacosx.com -+ ~brew cask install emacs~ (installs from emacsformacosx.com) -+ AquaMacs -+ XEmacs - -**** With MacPorts -There are four ports (at time of writing) available through MacPorts, and they -are all acceptable options: - -+ [[https://ports.macports.org/port/emacs/summary][emacs]] (27.2) and [[https://ports.macports.org/port/emacs-devel/summary][emacs-devel]] (28) -- Installs terminal-only Emacs -+ [[https://ports.macports.org/port/emacs-app/summary][emacs-app]] (27.2), [[https://ports.macports.org/port/emacs-app-devel/summary][emacs-app-devel]] (28) -- Installs GUI Emacs -+ [[https://ports.macports.org/port/emacs-mac-app/summary][emacs-mac-app]] (27.2) -- the [[https://bitbucket.org/mituharu/emacs-mac][Mitsuharu Yamamoto mac port]] - -Some of these ports do not add an =emacs= binary to your ~PATH~, which is -necessary for Doom's installation process. You'll have to do so yourself by -adding this to your shell config: - -#+BEGIN_SRC sh -# Add this to ~/.zshrc or ~/.bash_profile -export PATH="/Applications/MacPorts/Emacs.app/Contents/MacOS:$PATH" -#+END_SRC - -Or by replacing ~/usr/local/bin/emacs~ with a shim script containing: -#+BEGIN_SRC -#!/bin/sh -/Applications/MacPorts/Emacs.app/Contents/MacOS/Emacs "$@" -#+END_SRC - -*** On Windows -#+begin_quote -*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. -#+end_quote - -There are three methods for installing Emacs 27.x on Windows, each with their -pros and cons: - -+ With chocolatey/scoop -+ With a precompiled binary + Git Bash -+ With WSL2 + Ubuntu - -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: - -1. Create a ~HOME~ [[https://mywindowshub.com/how-to-edit-system-environment-variables-for-a-user-in-windows-10/][system environment variable]]. - - Set it to =C:\Users\USERNAME\=, otherwise Emacs will treat - =C:\Users\USERNAME\AppData\Roaming= as your ~HOME~, which will cause issues - later. - -2. Add =C:\Users\USERNAME\.emacs.d\bin= to your ~PATH~. - - 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). - - #+begin_quote - A pre-existing PATH variable should already exist among your system - variables. It contains a string of file paths separated by colons; - ~pathA:pathB:pathC~. Prepend the path to bin/doom to that string, like so: - ~C:\Users\username\.emacs.d\bin:pathA:pathB:pathC~ - #+end_quote - -3. Restart your system so your new values for ~HOME~ and ~PATH~ take effect. - -Now we're ready to move on! - -**** With [[https://chocolatey.org/][chocolatey]] / scoop -[[https://chocolatey.org/][Chocolatey]] is a package manager for Windows, and is the simplest way to install -Emacs and Doom's dependencies: -#+BEGIN_SRC sh -choco install git emacs ripgrep -# Optional dependencies -choco install fd llvm -#+END_SRC - -Scoop will work too, but because Emacs is a GUI application you'll need to -enable the 'extras' Scoop bucket: -#+BEGIN_SRC sh -scoop bucket add extras -scoop install git emacs ripgrep -# Optional dependencies -scoop install fd llvm -#+END_SRC - -**** With a precompiled binary + Git Bash -(Credit goes to @earvingad and [[https://earvingad.github.io/posts/doom_emacs_windows/][his fantastic tutorial]] for informing this guide) - -1. Download and install Git from https://git-scm.com/download/win -2. Download and extract Emacs, ripgrep and fd where you want them, but in - different folders: - - Emacs 27.2 from http://ftp.wayne.edu/gnu/emacs/windows/emacs-27/ - - Ripgrep from https://github.com/BurntSushi/ripgrep/releases - - (optional) fd from https://github.com/sharkdp/fd/releases -3. Add the three folders from step 2 to your ~PATH~ - - Go to Control panel -> User Accounts -> Change my environment variables. - - Click "New", type HOME and set your C:\Users\USERNAME and OK. - - Select "Path", click "edit", prepend =C:\path\to\the\emacs\bin:= to it and - click OK. - - Select "Path", click "edit", prepend =C:\path\to\the\ripgrep:= to it and - click OK. - - Select "Path", click "edit", prepend =C:\path\to\the\fd:= to it and click - OK. - - Click Ok. - -And done! Keep git-bash.exe open, you'll need it for the rest of this guide. - -#+begin_quote -*IMPORTANT:* you'll need to open git-bash.exe whenever you want to run a -bin/doom command. -#+end_quote - -**** 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) - -1. Install Powershell as admin (Windows key + x) with: - #+BEGIN_SRC - Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux - #+END_SRC -2. Restart your Computer -3. Download and install Ubuntu 18.04 L>TS from the Microsoft Store -4. Launch Ubuntu 18.04 LTS -5. Update and upgrade Ubuntu - #+BEGIN_SRC - sudo apt update && sudo apt upgrade - #+END_SRC -6. Then install Emacs: - #+BEGIN_SRC sh - sudo add-apt-repository ppa:kelleyk/emacs - sudo apt update - sudo apt install emacs27 - #+END_SRC -7. Then Doom's dependencies: - #+BEGIN_SRC sh - # required dependencies - sudo apt-get install git ripgrep - # optional dependencies - sudo apt-get install fd-find - #+END_SRC - -And done! Keep Ubuntu open, you'll need it for the rest of this guide. - -** Doom Emacs -With Emacs and Doom's dependencies installed, next is to install Doom Emacs -itself: - -#+BEGIN_SRC bash -git clone https://github.com/hlissner/doom-emacs ~/.emacs.d -~/.emacs.d/bin/doom install -#+END_SRC - -=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. - -If this is your first time, you should run ~doom doctor~. This will diagnose -common issues with your system or config. - -#+BEGIN_QUOTE -If you'd like a more technical break down of ~doom install~, it's been -translated into shell commands below, in the "Install Doom Manually" section. -#+END_QUOTE - -*** 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: - -+ ~doom sync~: This synchronizes your config with Doom Emacs. It ensures that - needed packages are installed, orphaned packages are removed and necessary - metadata correctly generated. Run this whenever you modify your ~doom!~ block - or =packages.el= file. You'll need ~doom sync -u~ if you override the recipe - of package installed by another module. -+ ~doom upgrade~: Updates Doom Emacs (if available) and all its packages. -+ ~doom env~: (Re)generates an "envvar file", which is a snapshot of your - shell environment that Doom loads at startup. If your app launcher or OS - launches Emacs in the wrong environment you will need this. **This is required - for GUI Emacs users on MacOS.** -+ ~doom doctor~: If Doom misbehaves, the doc will diagnose common issues with - your installation, system and environment. -+ ~doom purge~: Over time, the repositories for Doom's plugins will accumulate. - Run this command from time to time to delete old, orphaned packages, and with - the ~-g~ switch to compact existing package repos. - -Use ~doom help~ to see an overview of the available commands that =doom= -provides, and ~doom help COMMAND~ to display documentation for a particular -~COMMAND~. - -#+begin_quote -I recommend you add =~/.emacs.d/bin= to your ~PATH~ so you can call =doom= -directly and from anywhere. Accomplish this by adding this to your .bashrc or -.zshrc file: ~export PATH="$HOME/.emacs.d/bin:$PATH"~ -#+end_quote - -*** Install Doom Manually -If you'd rather install Doom yourself, instead of rely on the magic of =doom -install=, here is its equivalent in bash shell commands (assuming -=hlissner/doom-emacs= has been cloned to =~/.emacs.d=): - -#+BEGIN_SRC bash -# So we don't have to write ~/.emacs.d/bin/doom every time -PATH="$HOME/.emacs.d/bin:$PATH" - -# Create a directory for our private config -mkdir ~/.doom.d # or ~/.config/doom - -# The init.example.el file contains an example doom! call, which tells Doom what -# modules to load and in what order. -cp ~/.emacs.d/init.example.el ~/.doom.d/init.el -cp ~/.emacs.d/core/templates/config.example.el ~/.doom.d/config.el -cp ~/.emacs.d/core/templates/packages.example.el ~/.doom.d/packages.el - -# You might want to edit ~/.doom.d/init.el here and make sure you only have the -# modules you want enabled. - -# Then synchronize Doom with your config: -doom sync - -# If you know Emacs won't be launched from your shell environment (e.g. you're -# on macOS or use an app launcher that doesn't launch programs with the correct -# shell) then create an envvar file to ensure Doom correctly inherits your shell -# environment. -# -# If you don't know whether you need this or not, there's no harm in doing it -# anyway. `doom install` will have prompted you to generate one. If you -# responded no, you can generate it later with the following command: -doom env - -# Lastly, install the icon fonts Doom uses: -emacs --batch -f all-the-icons-install-fonts -# On Windows, `all-the-icons-install-fonts` will only download the fonts, you'll -# have to install them by hand afterwards! -#+END_SRC - -To understand the purpose of the =~/.doom.d= directory and =~/.doom.d/init.el= -file, see the [[#configure][Configure]] section further below. - -*** Install Doom alongside other configs (with Chemacs2) -[[https://github.com/plexus/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: - -1. First, install Doom somewhere: - #+BEGIN_SRC sh :eval no - git clone https://github.com/hlissner/doom-emacs ~/doom-emacs - ~/doom-emacs/bin/doom install - #+END_SRC - -2. Move aside any existing config and install Chemacs2 as your new =~/.emacs.d=: - #+BEGIN_SRC bash :eval no - [ -f ~/.emacs ] && mv ~/.emacs ~/.emacs.bak - [ -d ~/.emacs.d ] && mv ~/.emacs.d ~/.emacs.legacy - git clone https://github.com/plexus/chemacs2.git ~/.emacs.d - #+END_SRC - -3. Create =~/.emacs-profiles.el= with a list of your Emacs profiles. This file - is structured like a =.dir-locals.el= file. Here is an example with Doom (as - the default), Spacemacs, and Prelude: - #+BEGIN_SRC emacs-lisp :eval no - (("default" . ((user-emacs-directory . "~/doom-emacs"))) - ("legacy" . ((user-emacs-directory . "~/.emacs.legacy"))) - ("spacemacs" . ((user-emacs-directory . "~/spacemacs")))) - #+END_SRC - -To start Emacs with a specific config, use the =--with-profile= option: - -#+BEGIN_SRC bash -emacs --with-profile spacemacs -#+END_SRC - -If no profile is specified, the =default= profile is used. - -** External/system dependencies -Doom is comprised of approximately 160 modules which provide its features, -language support and integration with external tools. Many of these have -external dependencies that you must install yourself. You'll find what a module -needs and how to install them in that module's README.org file or by running -~bin/doom doctor~. - -The [[file:modules.org][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! - -#+begin_quote -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. -#+end_quote - -* Update & Rollback -Doom is an active project and many of its 300+ packages are in active -development as well. It is wise to occasionally update: -#+BEGIN_SRC bash -doom upgrade # or 'doom up' -#+END_SRC - -If you want to update Doom manually, ~doom upgrade~ is equivalent to: -#+BEGIN_SRC bash -cd ~/.emacs.d -git pull # updates Doom -doom clean # Ensure your config isn't byte-compiled -doom sync # synchronizes your config with Doom Emacs -doom update # updates installed packages -#+END_SRC - -To upgrade only your packages (and not Doom itself): - -#+BEGIN_SRC bash -doom upgrade --packages -#+END_SRC - -#+begin_quote -To minimize issues while upgrading, avoid modifying Doom's source files in -=~/.emacs.d=. All your customization should be kept in your =DOOMDIR= (e.g. -=~/.doom.d=). Read the [[#Configure][Configure]] section for more on configuring Doom. -#+end_quote - -** TODO Rollback -The =bin/doom= script doesn't currently offer rollback support for Doom or its -packages (yet). - -** Up/Downgrading Emacs -*You may encounter errors after up/downgrading Emacs.* Run ~doom sync~ on the -command line after changing the installed version of Emacs. If you've changed -the major version (e.g. 27 -> 28 or vice versa) run ~doom build~ too. - -+ ~doom sync~ will re-index any built-in/site loaddef files. This is especially - necessary if paths to built-in libraries have changed. -+ ~doom build~ will recompile all your installed packages, which is necessary - because Emacs bytecode not generally forward compatible across major releases - (e.g. 27 -> 28). Alternatively, reinstall all your packages by deleting - =~/.emacs.d/.local=, then run ~doom sync~. - -* TODO Migrate -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 does not use =package.el= to manage its packages, but ~use-package~ does! - You will see errors if you have ~:ensure ...~ properties in your ~use-package~ - blocks. Remove these and, instead, add ~package!~ declarations to - =~/.doom.d/packages.el= to install your packages. - - See [[#package-management]["Package Management"]], further in this guide. - -(This section is incomplete) - -** TODO From vanilla Emacs -#+begin_quote -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 [[https://discord.gg/qvGgnVx][on -our Discord server]]. -#+end_quote - -** TODO From Spacemacs -#+begin_quote -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 [[https://discord.gg/qvGgnVx][on our Discord -server]]. -#+end_quote - -* Configure -You can configure Doom by tweaking the files found in your =DOOMDIR=. Doom -expects this directory to be found in one of: - -1. =~/.config/doom= (respects ~$XDG_CONFIG_HOME~) -2. or =~/.doom.d= - -This directory is referred to as your =DOOMDIR=. Only one of these directories -should exist (Doom will only recognize one). - -#+begin_quote -Change the =DOOMDIR= environment variable to change where Doom looks for this -directory. Symlinks will work as well. -#+end_quote - -When you ran ~doom install~, it deployed a simple Doom configuration to your -=DOOMDIR=, comprised of these three files: - -+ 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. - -#+begin_quote -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. -#+end_quote - -** Modules -Doom consists of around 160 modules and growing. A Doom module is a bundle of -packages, configuration and commands, organized into a unit that can be toggled -easily by tweaking your ~doom!~ block (found in =$DOOMDIR/init.el=). - -#+begin_quote -If =$DOOMDIR/init.el= doesn't exist, you haven't run ~doom install~ yet. See [[#install][the -"Install" section]] above. -#+end_quote - -Your ~doom!~ block should look something like this: - -#+BEGIN_SRC emacs-lisp -;; To comment something out, you insert at least one semicolon before it and the -;; Emacs Lisp interpreter will ignore everything until the end of the line. -(doom! :lang - python ; this module is not commented, therefore enabled - ;;javascript ; this module is commented out, therefore disabled - ;;lua ; this module is disabled - ruby ; this module is enabled - php) ; this module is enabled -#+END_SRC - -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: - -#+BEGIN_SRC emacs-lisp -(doom! :completion - (company +childframe) - :lang - (csharp +unity) - (org +brain +dragndrop +gnuplot +hugo +jupyter) - (sh +fish)) -#+END_SRC - -Different modules support different flags. You'll find a comprehensive list of -available modules and their supported flags in [[file:modules.org][Module Index]]. Flags that a -module does not recognize will be silently ignored. - -#+begin_quote -*IMPORTANT:* any changes to your ~doom!~ block won't take effect until you run - ~doom sync~ on the command line. -#+end_quote - -#+begin_quote -~doom doctor~ will detect issues with your ~doom!~ block, such as duplicate or -misspelled modules and flags. -#+end_quote - -** Package management -**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 -[[https://github.com/raxod502/straight.el][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. - -#+begin_quote -*WARNING:* Do not install packages directly (with ~M-x package-install~ or ~M-x -straight-use-package~). Without an accompanying ~package!~ declaration somewhere -these packages will be forgotten when you restart Emacs and uninstalled the next -time you run ~doom sync~ or ~doom purge~. -#+end_quote - -#+begin_quote -*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! -#+end_quote - -*** Installing packages -To install a package, add a ~package!~ declaration for it to -=DOOMDIR/packages.el=: -#+BEGIN_SRC emacs-lisp -;; Install a package named "example" from ELPA, MELPA, or Emacsmirror -(package! example) -#+END_SRC - -If a package could not be found in any known repo you will get an error like: - -#+begin_quote -Could not find package X in recipe repositories: (org-elpa melpa gnu-elpa-mirror -emacsmirror-mirror) -#+end_quote - -The most likely cause for this is either: - -- You've misspelled the package's name. -- Or the package really doesn't exist on ELPA, MELPA, or EmacsMirror and you'll - need to [[*Installing packages from external sources][specify a recipe for it]]. - -~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. -#+BEGIN_SRC elisp -(when (package! example) - (package! plugin-that-example-depends-on)) -#+END_SRC - -#+begin_quote -*IMPORTANT:* New packages won't be installed until you run ~doom sync~. -#+end_quote - -*** Installing packages from external sources -To install a package straight from an external source (like github, gitlab, -etc), you'll need to specify a [[https://github.com/raxod502/straight.el#the-recipe-format][MELPA-style straight recipe]]: - -Here are a few examples: -#+BEGIN_SRC elisp -;; Install it directly from a github repository. For this to work, the package -;; must have an appropriate PACKAGENAME.el file which must contain at least a -;; Package-Version or Version line in its header. -(package! example - :recipe (:host github :repo "username/my-example-fork")) - -;; If the source files for a package are in a subdirectory in said repo, use -;; `:files' to target them. -(package! example :recipe - (:host github - :repo "username/my-example-fork" - :files ("*.el" "src/lisp/*.el"))) - -;; To grab a particular branch or tag: -(package! example :recipe - (:host gitlab - :repo "username/my-example-fork" - :branch "develop")) - -;; If a package has a default recipe on MELPA or emacsmirror, you may omit -;; keywords and the recipe will inherit the rest of the recipe from their -;; original. -(package! example :recipe (:branch "develop")) - -;; If the repo pulls in many unneeded submodules, you can disable recursive cloning -(package! example :recipe (:nonrecursive t)) - -;; A package can be installed straight from a git repo by setting :host to nil: -(package! example - :recipe (:host nil :repo "https://some/git/repo")) -#+END_SRC - -The specification for the ~package!~ macro's ~:recipe~ is laid out [[https://github.com/raxod502/straight.el#the-recipe-format][in -Straight.el's README]]. - -#+begin_quote -*IMPORTANT:* Run ~bin/doom sync~ whenever you modify packages.el files to -ensure your changes take effect. -#+end_quote - -*** 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: -#+BEGIN_SRC elisp -(package! evil :pin "e00626d9fd") -#+END_SRC - -To unpin a package, use the ~unpin!~ macro: -#+BEGIN_SRC elisp -(unpin! evil) - -;; It can be used to unpin multiple packages at once -(unpin! evil helm org-mode) - -;; Or to unpin all packages in modules -(unpin! (:lang python ruby rust) (:tools docker)) - -;; Or to unpin an entire category of modules -(unpin! :completion :lang :tools) - -;; This will work too, if you prefer the syntax, but it provides no concise -;; syntax for unpinning multiple packages: -(package! helm :pin nil) -#+END_SRC - -Though it is *highly* discouraged, you may unpin all packages and make Doom -Emacs rolling release: -#+BEGIN_SRC elisp -(unpin! t) -#+END_SRC - -#+begin_quote -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. -#+end_quote - -*** Disabling packages -The ~package!~ macro possesses a ~:disable~ property: -#+BEGIN_SRC emacs-lisp -(package! irony :disable t) -(package! rtags :disable t) -#+END_SRC - -Once a package is disabled, ~use-package!~ and ~after!~ blocks for it will be -ignored, and the package is removed the next time you run ~bin/doom sync~. Use -this to disable Doom's packages that you don't want or need. - -There is also the ~disable-packages!~ macro for conveniently disabling multiple -packages: -#+BEGIN_SRC elisp -(disable-packages! irony rtags) -#+END_SRC - -#+begin_quote -*IMPORTANT:* Run ~bin/doom sync~ whenever you modify packages.el files to -ensure your changes take effect. -#+end_quote - -*** Changing a recipe for an included package -If a Doom module installs package X from one place, but you'd like to install it -from another (say, a superior fork), add a ~package!~ declaration for it in your -=DOOMDIR/packages.el=. Your private declarations always have precedence over -modules (even your own). -#+BEGIN_SRC elisp -;; in modules/editor/evil/packages.el -(package! evil) ; installs from MELPA - -;; in DOOMDIR/packages.el -(package! evil :recipe (:host github :repo "username/my-evil-fork")) -#+END_SRC - -To install a package only if a built-in package doesn't exist, use ~:built-in -'prefer~: -#+BEGIN_SRC elisp -(package! so-long :built-in 'prefer) -#+END_SRC - -#+begin_quote -*IMPORTANT:* Remember to run ~doom sync -u~ after changing recipes for existing -packages. At the time of writing, ~doom sync~ alone will not pick up on recipe -changes. -#+end_quote - -*** 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: -#+BEGIN_SRC elisp -(package! my-package - :recipe (:local-repo "/path/to/my/package")) - -;; Relative paths are expanded to ~/.emacs.d/.local/straight/repos/{local-repo} -;; or ~/.doom.d/{local-repo} -- the first that is found. -(package! my-package - :recipe (:local-repo "my/package")) ; looks for ~/.doom.d/my/package/my-package.el - -(package! my-package - :recipe (:local-repo "/path/to/my/package" - - ;; By default, the package manager grabs all *.el files at the root - ;; of the project and nothing else. To include other files, or - ;; accommodate unconventional project structures, specify what :files - ;; you want: - :files ("*.el" "src/lisp/*.el") - - ;; With this you can avoid having to run 'doom sync' every time you - ;; change the package. - :build (:not compile))) -#+END_SRC - -Alternatively, add the package's location to Emacs' ~load-path~. Do this if you -don't need/care for autoload cookies or byte-compilation: -#+BEGIN_SRC elisp -;; Doom has modified `use-package's `:load-path' to expand relative paths from -;; your DOOMDIR. e.g. ~/.doom.d/lisp/package -(use-package my-package - :load-path "lisp/package") - -;; or - -(add-load-path! "lisp/package") -#+END_SRC - -#+begin_quote -*IMPORTANT:* Remember to run ~doom sync~ to rebuild your package after you've -changed it, and to re-index any autoloads in it. -#+end_quote - -** Configuring Doom -*** Configuring packages -If your configuration needs are simple, the ~use-package!~, ~after!~, -~add-hook!~ and ~setq-hook!~ macros are your bread and butter. - -#+BEGIN_SRC emacs-lisp -;;; ~/.doom.d/config.el (example) -(setq doom-font (font-spec :family "Fira Mono" :size 12)) - -;; Takes a feature symbol or a library name (string) -(after! evil - (setq evil-magic nil)) - -;; Takes a major-mode, a quoted hook function or a list of either -(add-hook! python-mode - (setq python-shell-interpreter "bpython")) - -;; These are equivalent -(setq-hook! 'python-mode-hook python-indent-offset 2) -(setq-hook! python-mode python-indent-offset 2) - -(use-package! hl-todo - ;; if you omit :defer, :hook, :commands, or :after, then the package is loaded - ;; immediately. By using :hook here, the `hl-todo` package won't be loaded - ;; until prog-mode-hook is triggered (by activating a major mode derived from - ;; it, e.g. python-mode) - :hook (prog-mode . hl-todo-mode) - :init - ;; code here will run immediately - :config - ;; code here will run after the package is loaded - (setq hl-todo-highlight-punctuation ":")) -#+END_SRC - -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 ~use-package!~ block*. -Therefore it must be used from your private init.el file. - -#+BEGIN_SRC emacs-lisp -;;; ~/.doom.d/init.el (example) -;; If a :pre-init / :pre-config hook returns nil, it overwrites that package's -;; original :init / :config block. Exploit this to overwrite Doom's config. -(use-package-hook! doom-themes - :pre-config - (setq doom-neotree-file-icons t) - nil) - -;; ...otherwise, make sure they always return non-nil! -(use-package-hook! evil - :pre-init - (setq evil-magic nil) - t) - -;; `use-package-hook' also has :post-init and :post-config hooks -#+END_SRC - -*** 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. - -+ Evil users can use the =gr= operator to evaluate a segment of code. The return - value is displayed in the minibuffer or in a popup (if the result is large - enough to warrant one). - - =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. -+ Non-evil users can use =C-x C-e= to run ~eval-last-sexp~, as well as ~M-x - +eval/buffer-or-region~ (on =SPC c e=). -+ Another option is to open a scratch buffer with =SPC x=, change its major mode - (~M-x emacs-lisp-mode~), and use the above keys to evaluate your code. -+ An ielm REPL is available by pressing =SPC o r= - (~+eval/open-repl-other-window~). -+ There's also =M-:= or =SPC ;=, which invokes ~eval-expression~, which you can - use to run elisp code inline. - -While all this is helpful for reconfiguring your running Emacs session, it can -also be helpful for debugging. - -*** TODO Binding keys -+ define-key -+ global-set-key -+ map! -+ undefine-key! -+ define-key! - -** Writing your own modules -To create your own module you need only create a directory for it in -=~/.doom.d/modules/abc/xyz=, then add =:abc xyz= to your ~doom!~ block in -=~/.doom.d/init.el= to enable it. - -#+begin_quote -In this example, =:abc= is called the category and =xyz= is the name of the -module. Doom refers to modules in one of two formats: =:abc xyz= and =abc/xyz=. -#+end_quote - -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: - -+ A =packages.el= to declare all the packages it will install, -+ A =config.el= to configure and load those packages, -+ And, sometimes, an =autoload.el= to store that module's functions, to be - loaded when they are used. - -These are a few exceptional examples of a well-rounded module: -+ [[file:../modules/completion/company/README.org][:completion company]] - -The remainder of this guide will go over the technical details of a Doom module. - -*** File structure -Doom recognizes a handful of special file names, none of which are required for -a module to function. They are: - -#+begin_example -category/ - module/ - test/*.el - autoload/*.el - autoload.el - init.el - cli.el - config.el - packages.el - doctor.el -#+end_example - -**** =init.el= -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). - -Do: -+ Configure Emacs or perform setup/teardown operations that must be set early; - before other modules are (or this module is) loaded. -+ Reconfigure packages defined in Doom modules with ~use-package-hook!~ (as a - last resort, when ~after!~ and hooks aren't enough). -+ Configure behavior of =bin/doom= in a way that must also apply in - interactive sessions. - -Don't: -+ Configure packages with ~use-package!~ or ~after!~ from here -+ Preform expensive or error-prone operations; these files are evaluated - whenever =bin/doom= is used; a fatal error in this file can make Doom - unbootable (but not irreversibly). -+ Define new =bin/doom= commands here. That's what =cli.el= is for. - -**** =config.el= -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. - -Do: -+ Use ~after!~ or ~use-package!~ to configure packages. - #+BEGIN_SRC emacs-lisp - ;; from modules/completion/company/config.el - (use-package! company ; `use-package!' is a thin wrapper around `use-package' - ; it is required that you use this in Doom's modules, - ; but not required to be used in your private config. - :commands (company-mode global-company-mode company-complete - company-complete-common company-manual-begin company-grab-line) - :config - (setq company-idle-delay nil - company-tooltip-limit 10 - company-dabbrev-downcase nil - company-dabbrev-ignore-case nil) - [...]) - #+END_SRC -+ Lazy load packages with ~use-package~'s ~:defer~ property. -+ Use the ~featurep!~ macro to make some configuration conditional based on the - state of another module or the presence of a flag. - -Don't: -+ Use ~package!~ -+ Install packages with =package.el= or ~use-package~'s ~:ensure~ property. Doom - has its own package manager. That's what =packages.el= is for. - -**** =packages.el= -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). - -Do: -+ Declare packages with the ~package!~ macro -+ Disable single packages with ~package!~'s ~:disable~ property or multiple - packages with the ~disable-packages!~ macro. -+ Use the ~featurep!~ macro to make packages conditional based on the state of - another module or the presence of a flag. - -Don't: -+ Configure packages here (definitely no ~use-package!~ or ~after!~ in here!). - This file is read in an isolated environment and will have no lasting effect. - The only exception is configuration targeting =straight.el=. -+ Perform expensive calculations. These files are read often and sometimes - multiple times. -+ Produce any side-effects, for the same reason. - -#+begin_quote -The "[[#package-management][Package Management]]" section goes over the ~package!~ macro and how to deal -with packages. -#+end_quote - -**** =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). - -This is all made possible thanks to these autoload cookie: ~;;;###autoload~. -Placing this on top of a lisp form will do one of two things: - -1. Add a ~autoload~ call to Doom's autoload file (found in - =~/.emacs.d/.local/autoloads.el=, which is read very early in the startup - process). -2. Or copy that lisp form to Doom's autoload file verbatim (usually the case for - anything other than ~def*~ forms, like ~defun~ or ~defmacro~). - -Doom's autoload file is generated by scanning these files when you execute ~doom -sync~. - -For example: -#+BEGIN_SRC emacs-lisp -;; from modules/lang/org/autoload/org.el -;;;###autoload -(defun +org/toggle-checkbox () - (interactive) - [...]) - -;; from modules/lang/org/autoload/evil.el -;;;###autoload (autoload '+org:attach "lang/org/autoload/evil" nil t) -(evil-define-command +org:attach (&optional uri) - (interactive "") - [...]) -#+END_SRC - -**** =doctor.el= -When you execute ~doom doctor~, this file defines a series of tests for the -module. These should perform sanity checks on the environment, such as: - -+ Check if the module's dependencies are satisfied, -+ Warn if any of the enabled flags are incompatible, -+ Check if the system has any issues that may interfere with the operation of - this module. - -Use the ~warn!~, ~error!~ and ~explain!~ macros to communicate issues to the -user and, ideally, explain how to fix them. - -For example, the ~:lang cc~ module's doctor checks to see if the irony server is -installed: -#+BEGIN_SRC emacs-lisp -;; from lang/cc/doctor.el -(require 'irony) -(unless (file-directory-p irony-server-install-prefix) - (warn! "Irony server isn't installed. Run M-x irony-install-server")) -#+END_SRC - -**** TODO =cli.el= -This file is read when =bin/doom= starts up. Use it to define your own CLI -commands or reconfigure existing ones. - -**** TODO =test/**/test-*.el= -Doom's unit tests go here. More information on them to come... - -**** Additional files -Any files beyond the ones I have already named are not given special treatment. -They must be loaded manually to be loaded at all. In this way modules can be -organized in any way you wish. Still, there is one convention that has emerged -in Doom's community that you may choose to adopt: extra files in the root of the -module are prefixed with a plus, e.g. =+extra.el=. There is no syntactical or -functional significance to this convention. - -These can be loaded with the ~load!~ macro, which will load an elisp file -relative to the file it's used from. e.g. - -#+BEGIN_SRC emacs-lisp -;; Omitting the file extension allows Emacs to load the byte-compiled version, -;; if it is available: -(load! "+git") ; loads ./+git.el -#+END_SRC - -This can be useful for splitting up your configuration into multiple files, -saving you the hassle of creating multiple modules. - -*** Load order -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 | -|---------------------------------------------+-------------+-------+-----| -| ~/.emacs.d/early-init.el (Emacs 27+ only) | yes | no | no | -| ~/.emacs.d/init.el | 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 | - -*** Flags -A module's flag is an arbitrary symbol. By convention, these symbols are -prefixed with a ~+~ or a ~-~ to denote the addition or removal of a feature, -respectively. There is no functional significance to this notation. - -A module may choose to interpret flags however it wishes, and can be tested for -using the ~featurep!~ macro: - -#+BEGIN_SRC elisp -;; Has the current module been enabled with the +my-feature flag? -(when (featurep! +my-feature) ...) - -;; It can be used to check the presence of flags in other modules: -(when (featurep! :lang python +lsp) ...) -#+END_SRC - -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. - -*** Doom cookies -Autoload cookies were mentioned [[*=autoload/*.el= OR =autoload.el=][earlier]]. A couple more exist that are specific -to Doom Emacs. This section will go over what they do and how to use them. - -**** ~;;;###if~ -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~). - -i.e. if =FORM= returns ~nil~, Doom will neither index its ~;;;###autoload~ -cookies nor byte-compile the file. - -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: -#+BEGIN_SRC emacs-lisp -;;;###if (featurep! +particular-flag) -#+END_SRC - -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: -#+BEGIN_SRC emacs-lisp -;;;###if (not (locate-library "so-long")) -#+END_SRC - -#+begin_quote -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. -#+end_quote - -**** ~;;;###package~ -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: - -+ ~after!~ calls -+ ~use-package!~ or ~use-package~ calls -+ and ~;;;###package X~ cookies, where X is the name of the package - -Use it to let ~doom/help-packages~ know where to find config for packages where -no ~after!~ or ~use-package!~ call is involved. - -**** ~;;;###autodef~ -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). - -#+begin_quote -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. -#+end_quote - -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: -#+BEGIN_SRC elisp -;;;###autodef -(defun set-something! (value) - ...) -#+END_SRC - -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: -#+BEGIN_SRC emacs-lisp -(set-company-backend! 'python-mode '(company-anaconda)) -#+END_SRC - -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 -You don't need ~org-babel-do-load-languages~. Doom lazy loads babel packages -based on the language name in ~#+BEGIN_SRC~ blocks needed. As long as the babel -plugin is installed and the plugin is named after its language (e.g. -~#+BEGIN_SRC rust~ will load ~ob-rust~), you don't need to do anything else. - -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 [[file:../modules/lang/org/README.org][:lang -org module documentation]] for details on how to add support for it. - -*** Using ~delete-trailing-whitespaces~ or ~whitespace-cleanup~ to manage leftover whitespace -#+BEGIN_SRC elisp -(add-hook 'after-save-hook #'delete-trailing-whitespace) -;; or -(add-hook 'after-save-hook #'whitespace-cleanup) -#+END_SRC - -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: - -1. It only cleans up trailing whitespace /on lines that you've touched/ (but - always strips newlines at EOF). - - 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! - - However, if it's truly deliberate, ~M-x delete-trailing-whitespaces~ and ~M-x - whitespace-cleanup~ are available to be called =deliberately=, instead. - -2. =ws-butler= replaces trailing whitespace and newlines with *virtual* - whitespace. This is whitespace that only exists in the Emacs buffer, but - isn't actually written to the file. - - 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. - -* Troubleshoot -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: - -+ Investigate the =*Messages*= log for warnings or error messages. This log can - be opened with =SPC h e=, =C-h e= or =M-x view-echo-area-messages=. - -+ Look up errors/warnings [[file:faq.org::Common Issues][on the FAQ]] and [[https://github.com/hlissner/doom-emacs/issues][Doom's issue tracker]]. It is possible - that a solution for your issue already exists. The FAQ can be searched from - inside Doom with =SPC h d f= (or =C-h d f= for non-evil users). - -+ Run ~bin/doom doctor~ on the command line to diagnose common issues with your - environment and config. It will suggest solutions for them as well. - -+ ~bin/doom clean~ will ensure the problem isn't stale bytecode in your private - config or Doom core. If you haven't used ~bin/doom compile~, there's no need - to do this. - -+ ~bin/doom sync~ will ensure the problem isn't missing packages or outdated - autoloads files - -+ ~bin/doom build~ will ensure the problem isn't stale package bytecode or - broken symlinks. - -+ ~bin/doom update~ will ensure that your packages are up-to-date, eliminating - issues that originate from upstream. - -+ If you happen to know what module(s) are relevant to your issue, check their - documentation (press = h d m= to jump to a module's documentation). Your - issue may be documented. - -+ If possible, see if the issue can be reproduced in vanilla Emacs (Emacs - without Doom) and/or vanilla Doom (Doom without your private config). [[#testing-in-dooms-sandbox][Doom's - sandbox can help you check]]. - -+ Ask for help on [[https://discord.gg/qvGgnVx][our Discord server]]. It is the quickest way to get help, - sometimes straight from Doom's maintainer, who is very active there. - -If none of these things have helped you, then it's time to open a bug report. -See "[[file:contributing.org::*Reporting issues][Reporting Issues]]" in the [[file:contributing.org][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: - -+ ~describe-variable~ (=SPC h v=) -+ ~describe-function~ (=SPC h f=) -+ ~describe-face~ (=SPC h F=) -+ ~describe-bindings~ (=SPC h b=) -+ ~describe-key~ (=SPC h k=) -+ ~describe-char~ (=SPC h '=) -+ ~find-library~ (=SPC h P=) - -You can also evaluate code with ~eval-expression~ (=M-;= or =SPC ;=). - -*** TODO For Doom Modules, packages, autodefs, etc. -+ ~doom/open-news~ (=SPC h n=) :: - ... -+ ~doom/help~ (=SPC h d h=) :: - Open the index of Doom's manual. -+ ~doom/help-modules~ (=SPC h d m=) :: - Jumps to a module's documentation. -+ ~doom/help-autodefs~ (=SPC h u=) :: - Jumps to the documentation for an autodef function/macro. These are special - functions that are always defined, whether or not their containing modules - are enabled. -+ ~doom/help-packages~ (=SPC h p=) :: - Look up packages that are installed, by whom (what modules) and where jump - to all the places it is being configured. -+ ~doom/info~ :: - ... - -** 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 [[https://discord.gg/qvGgnVx][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. - -*** Enabling ~debug-on-error~ -There are three ways to enable ~debug-on-error~: - -1. Start Emacs with ~emacs --debug-init~. Use this for errors that occur at - startup. -2. Evil users can press =SPC h d d= and non-evil users can press =C-h d d=. -3. If the above don't work, there's always: ~M-x toggle-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~ -If the error you've encountered is emitted from ~bin/doom~, you can re-run the -same command with the ~-d~ or ~--debug~ switches to force it to emit a backtrace -when an error occurs. The ~DEBUG~ environment variable will work to. - -#+BEGIN_SRC sh -doom -d sync -doom --debug install -DEBUG=1 doom update -#+END_SRC - -#+BEGIN_QUOTE -Note: switch order is important. ~-d~ / ~--debug~ /must/ come right after ~doom~ -and before the subcommand. This will be fixed eventually. -#+END_QUOTE - -** 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: - -+ Use =M-:= (bound to ~eval-expression~), -+ =SPC x= will open a scratch buffer. ~M-x emacs-lisp-mode~ will change it to - the appropriate major mode, then use ~+eval:region~ (=gr=) and ~+eval/buffer~ - (=gR=) to evaluate code, - -** 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: - -+ =SPC h E= (for evil users) -+ =C-h E= (for non-evil users) -+ ~M-x doom/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. - -#+BEGIN_QUOTE -All new instances will inherit your ~load-path~ so you can access any packages -you have installed. -#+END_QUOTE -*** Testing packages in the sandbox -Instances of Emacs launched from the sandbox have inherited your ~load-path~. -This means you can load packages -- even in Vanilla Emacs -- without worrying -about installing or setting them up. Just ~(require PACKAGE)~ and launch the -sandbox. e.g. - -#+BEGIN_SRC elisp -(require 'magit) -(find-file "~/some/file/in/a/repo") -(call-interactively #'magit-status) -#+END_SRC - -** TODO Bisecting your private config -** TODO Bisecting Doom Emacs diff --git a/docs/modules.org b/docs/modules.org deleted file mode 100644 index 2703f52e7..000000000 --- a/docs/modules.org +++ /dev/null @@ -1,1505 +0,0 @@ -:PROPERTIES: -:ID: 12d2de30-c569-4b8e-bbc7-85dd5ccc4afa -:END: -← [[doom-index:][Back to index]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help:][Help]] --------------------------------------------------------------------------------- -#+TITLE: Module Index -#+SUBTITLE: An exhaustive list of Doom's modules -#+SETUPFILE: .setupfile.org -#+STARTUP: nonum show2levels -#+MACRO: modules-in (eval (length (cl-remove-if-not #'file-directory-p (doom-glob doom-modules-dir $1)))) - -Doom’s features are divided into modules; a module is a collection of packages, -configuration, and commands, organized into a unit that can be easily enabled or -disabled by adding or removing them from your ~doom!~ block in -=$DOOMDIR/init.el= (remember to run ~$ doom sync~ and restart Emacs whenever -changing your doom! block). - -#+begin_quote - 📌 Looking for technical documentation on Doom's modules? That's in our - [[file:developers.org::*Modules][developer's manual]]. -#+end_quote - -At the time of writing, Doom has {{{modules-in(*/*)}}} modules. - -# Don't modify module list by hand! -* [[doom-module::app][:app]] ({{{modules-in(app/*)}}}) -Application modules are complex and opinionated modules that transform Emacs -toward a specific purpose. They may have additional dependencies and *should be -loaded last*, before [[doom-module:][:config]] modules. - -** [[doom-module::app calendar][calendar]]: - -: Watch your missed deadlines in real time - -This module adds a calendar view for Emacs, with org and google calendar sync -support. - -** [[doom-module::app emms][emms]]: - -: A media player for music no one’s heard of - -This module enables Emacs to be used as a music player. It uses [[https://www.musicpd.org/][mpd]] as a backend -server and [[https://musicpd.org/clients/mpc/][mpc]] to update your music database. - -** [[doom-module::app everywhere][everywhere]]: - -: *leave* Emacs!? You must be joking - -This module adds system-wide popup Emacs windows for quick edits. - -** [[doom-module::app irc][irc]]: - -: How neckbeards socialize - -This module turns Emacs into an IRC client, capable of OS notifications. - -** [[doom-module::app rss][rss]]: [[doom-module::app rss +org][+org]] -: An RSS reader that Google can’t shut down - -Read RSS feeds in the comfort of Emacs. - -** [[doom-module::app twitter][twitter]]: - -: Be superficial in plain text - -Enjoy twitter from emacs. - -- View various timelines side by side, e.g. user's timeline, home, etc. -- Post new tweets -- Send direct messages -- Retweet -- Follow and un-follow users -- Favorite tweets - - -* [[doom-module::checkers][:checkers]] ({{{modules-in(checkers/*)}}}) -For modules dedicated to linting text. - -** [[doom-module::checkers grammar][grammar]]: - -: Tasing grammar mistake every you make - -This module adds grammar checking to Emacs to aid your writing by combining -[[doom-package:][lang-tool]] and [[doom-package:][writegood-mode]]. - -** [[doom-module::checkers spell][spell]]: [[doom-module::checkers spell +aspell][+aspell]] [[doom-module::checkers spell +enchant][+enchant]] [[doom-module::checkers spell +everywhere][+everywhere]] [[doom-module::checkers spell +flyspell][+flyspell]] [[doom-module::checkers spell +hunspell][+hunspell]] -: Tasing you for misspelling mispelling - -This modules provides spellchecking powered by =aspell=, =hunspell= or -=enchant=. - -Spellcheck is automatically loaded in many ~text-mode~ derivatives, which -includes ~org-mode~, ~markdown-mode~, the Git Commit buffer (from magit), -~mu4e-compose-mode~, and others. - -- Spell checking and correction using =aspell=, =hunspell= or =enchant=. -- Ignores source code inside org or markdown files. -- Lazily spellchecking recent changes only when idle. -- Choosing suggestions using completion interfaces ([[doom-package:][ivy]] or [[doom-package:][helm]]). - -** [[doom-module::checkers syntax][syntax]]: [[doom-module::checkers syntax +childframe][+childframe]] -: Tasing you for every semicolon you forget - -This module provides syntax checking and error highlighting, powered by -[[doom-package:][flycheck]]. - - -* [[doom-module::completion][:completion]] ({{{modules-in(completion/*)}}}) -These modules provide interfaces and frameworks completion, including code -completion. - -** [[doom-module::completion company][company]]: [[doom-module::completion company +childframe][+childframe]] [[doom-module::completion company +tng][+tng]] -: The ultimate code completion backend - -This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. It is required -for code completion in many of Doom's :lang modules. - -https://assets.doomemacs.org/completion/company/overlay.png - -** [[doom-module::completion helm][helm]]: [[doom-module::completion helm +childframe][+childframe]] [[doom-module::completion helm +fuzzy][+fuzzy]] [[doom-module::completion helm +icons][+icons]] -: the *other* search engine for love and life - -This module provides Helm integration for a variety of Emacs commands, as well -as a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep][ripgrep]]. - -** [[doom-module::completion ido][ido]]: - -: A foil for other search engines - -Interactive DO things. The completion engine that is /mostly/ built-into Emacs. - -** [[doom-module::completion ivy][ivy]]: [[doom-module::completion ivy +childframe][+childframe]] [[doom-module::completion ivy +fuzzy][+fuzzy]] [[doom-module::completion ivy +icons][+icons]] [[doom-module::completion ivy +prescient][+prescient]] -: Yesterday's lightest search engine - -This module provides Ivy integration for a variety of Emacs commands, as well as -a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]]. - -#+begin_quote -I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's -lighter, simpler and faster in many cases. -#+end_quote - -** [[doom-module::completion vertico][vertico]]: [[doom-module::completion vertico +icons][+icons]] -: The search engine for life and love - -This module enhances the Emacs [[doom-changelog:module=":completion vertico"][search]] and [[file:~/projects/conf/doom-emacs/docs/changelog.org::/:completion vertico/][completion]] experience, and also -provides a united interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]]. - -It does this with several modular packages focused on enhancing the built-in -~completing-read~ interface, rather than replacing it with a parallel ecosystem -like [[doom-package:][ivy]] and [[doom-package:][helm]] do. The primary packages are: - -- Vertico, which provides the vertical completion user interface -- Consult, which provides a suite of useful commands using ~completing-read~ -- Embark, which provides a set of minibuffer actions -- Marginalia, which provides annotations to completion candidates -- Orderless, which provides better filtering methods - - -* [[doom-module::config][:config]] ({{{modules-in(config/*)}}}) -Modules that configure Emacs one way or another, or focus on making it easier -for you to customize it yourself. It is best to load these last. - -** [[doom-module::config default][default]]: - -: Reasonable defaults for reasonable people - -This module provides a set of reasonable defaults, including: - -- A Spacemacs-esque keybinding scheme -- Extra Ex commands for evil-mode users -- A configuration for (almost) universally repeating searches with [[kbd:][;]] and [[kbd:][,]] - -** [[doom-module::config literate][literate]]: - -: Disguise your config as documentation - -This module enables support for a literate config. - -A literate config consists of a =$DOOMDIR/config.org=. All src blocks within are -tangled =$DOOMDIR/config.el=, by default, when ~$ doom sync~ is executed. - - -* [[doom-module::editor][:editor]] ({{{modules-in(editor/*)}}}) -For modules concerned with the insertion, manipulation, and general editing of -text. Amen. - -** [[doom-module::editor evil][evil]]: [[doom-module::editor evil +everywhere][+everywhere]] -: Come to the dark side, we have cookies - -This holy module brings the vim experience to Emacs. - -** [[doom-module::editor file-templates][file-templates]]: - -: Fill the void in your empty files - -This module adds file templates for blank files, powered by [[doom-package:][yasnippet]]. - -** [[doom-module::editor fold][fold]]: - -: What you can't see won't hurt you - -This module marries [[doom-package:][hideshow]], [[doom-package:][vimish-fold]], and ~outline-minor-mode~ to bring you -marker, indent and syntax-based code folding for as many languages as possible. - -** [[doom-module::editor format][format]]: [[doom-module::editor format +onsave][+onsave]] -: Standardize your ugly code - -This module integrates code formatters into Emacs. Here are some of the -formatters that it currently supports: - -#+begin_quote -asmfmt, black, brittany, cabal-fmt, clang-format, cmake-format, dartfmt, dfmt, -dhall format, dockfmt, elm-format, emacs, fish_indent, fprettify, gleam format, -gofmt, iStyle, jsonnetfmt, ktlint, latexindent, ledger-mode, lua-fmt, mix -format, nixfmt, node-cljfmt, ocp-indent, perltidy, prettier, purty, rufo, -rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy -#+end_quote - -** [[doom-module::editor god][god]]: - -: IDDQD - -Adds [[doom-package:][god-mode]] support to Doom Emacs, allowing for entering commands without -modifier keys, similar to Vim's modality, separating command mode and insert -mode. - -** [[doom-module::editor lispy][lispy]]: - -: Vim for lisp, for people who don't like vim - -This module adds [[https://github.com/noctuid/lispyville][lispy]] key functionality in Lisp languages, including: - -- Common Lisp -- Emacs Lisp -- Scheme -- Racket -- [[http://docs.hylang.org/en/stable/][Hy]] -- [[http://lfe.io/][LFE]] -- Clojure -- [[https://fennel-lang.org][Fennel]] - -If [[doom-module:][:editor evil]] is enabled, lispyville would also be activated for every mode -where lispy is active - -The default key themes that are set are as follows: -#+begin_src emacs-lisp -'((operators normal) - c-w - (prettify insert) - (atom-movement normal visual) - slurp/barf-lispy - additional - additional-insert) -#+end_src - -To change the key themes set ~lispyville-key-theme~. Think of -~lispyville-key-theme~ as the equivalent of ~parinfer-extensions~. See -lispyville's [[https://github.com/noctuid/lispyville/blob/master/README.org][README]] for more info on the specific keybindings of each key theme -(starting [[https://github.com/noctuid/lispyville#operators-key-theme][here]]). - -** [[doom-module::editor multiple-cursors][multiple-cursors]]: - -: Make all your mistakes at the same time - -This module adds a multiple cursors implementation to Emacs (two, if you use -evil) that loosely take after multi-cursors in modern editors, like Atom or -Sublime Text. - -** [[doom-module::editor objed][objed]]: [[doom-module::editor objed +manual][+manual]] -: Text object editing for the innocent - -This modules adds [[doom-package:][objed]], a global minor-mode for navigating and manipulating -text objects. It combines the ideas of ~versor-mode~ and other editors like Vim -or Kakoune and tries to align them with regular Emacs conventions. - -#+begin_quote - 🚧 This module is incompatible with the [[doom-module:][:editor evil]]. Enabling them both will - cause errors. -#+end_quote - -[[https://github.com/clemera/objed][See the objed project README]] for information on keybinds and usage. - -** [[doom-module::editor parinfer][parinfer]]: - -: For lispers that like Python more (i.e. nobody) - -Parinfer is a minor mode that aids the writing of Lisp code. It automatically infers parenthesis matching and indentation alignment, keeping your code balanced and beautiful. - -https://raw.githubusercontent.com/DogLooksGood/parinfer-mode/a7c041454e05ec2b88333a73e72debaa671ed596/images/demo.gif - -#+begin_quote - 🚧 The original [[doom-package:][parinfer-mode]] has been deprecated and superceded by - [[doom-package:][parinfer-rust-mode]], which has much better performance. -#+end_quote - -** [[doom-module::editor rotate-text][rotate-text]]: - -: The only back'n'forth nerds will ever know - -This module adds text rotation to Doom Emacs. I.e. The ability to cycle through -keywords or text patterns at point, like ~true~ and ~false~, or ~public~, -~protected~, and ~private~ (in ~c++-mode~). - -** [[doom-module::editor snippets][snippets]]: - -: My elves type so I don't have to - -This module adds snippet expansions to Emacs, powered by [[doom-package:][yasnippet]]. - -** [[doom-module::editor word-wrap][word-wrap]]: - -: Soft-wrapping with language-aware indent - -This module adds a minor-mode ~+word-wrap-mode~, which intelligently wraps long -lines in the buffer without modifying the buffer content. - - -* [[doom-module::emacs][:emacs]] ({{{modules-in(emacs/*)}}}) -Modules in this category augment and extend the built-in features of Emacs. - -** [[doom-module::emacs dired][dired]]: [[doom-module::emacs dired +icons][+icons]] [[doom-module::emacs dired +ranger][+ranger]] -: Making dired pretty [functional] - -This module provides reasonable defaults and augmentations for dired. - -** [[doom-module::emacs electric][electric]]: - -: Shocking keyword-based electric-indent - -This module augments the built-in =electric= package with keyword-based -indentation (as opposed to character-based). - -** [[doom-module::emacs ibuffer][ibuffer]]: [[doom-module::emacs ibuffer +icons][+icons]] -: Edit me like your French buffers - -This module augments the built-in [[doom-package:][ibuffer]] package. - -- Adds project-based grouping of buffers -- Support for file-type icons -- Uses human-readable file-size - -** tramp: - -/(No description)/ - -** [[doom-module::emacs undo][undo]]: [[doom-module::emacs undo +tree][+tree]] -: Persistent, smarter undo for your inevitable mistakes - -This module augments Emacs' built-in undo system to be more intuitive and to -persist across Emacs sessions. - -** [[doom-module::emacs vc][vc]]: - -: Be the difference you want to see in the fringe - -This module augments Emacs builtin version control support and provides better -integration with =git=. - - -* [[doom-module::email][:email]] ({{{modules-in(email/*)}}}) -Modules that turn Emacs in an email client. - -** [[doom-module::email mu4e][mu4e]]: [[doom-module::email mu4e +gmail][+gmail]] [[doom-module::email mu4e +org][+org]] -: The great filter Hanson hadn't anticipated - -This module makes Emacs an email client, using [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]]. - -- Tidied mu4e headers view, with flags from [[doom-package:][all-the-icons]]. -- Consistent coloring of reply depths (across compose and gnus modes). -- Prettified =mu4e:main= view. -- Cooperative locking of the =mu= process. Another Emacs instance may request - access, or grab the lock when it's available. -- [[doom-package:][org-msg]] integration with [[doom-module:][+org]], which can be toggled per-message, with revamped - style and an accent color. -- Gmail integrations with the [[doom-module:][+gmail]] flag. -- Email notifications with [[doom-package:][mu4e-alert]], and (on Linux) a customised notification - style. - -#+begin_quote - 💡 I want to live in Emacs, but as we all know, living is incomplete without - email. So I prayed to the text editor gods and they (I) answered. - Emacs+evil's editing combined with org-mode for writing emails? /Yes - please./ - - It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my - email via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can - understand). -#+end_quote - -** [[doom-module::email notmuch][notmuch]]: [[doom-module::email notmuch +afew][+afew]] [[doom-module::email notmuch +org][+org]] -: Closest Emacs will ever be to multi-threaded - -This module turns Emacs into an email client using [[doom-package:][notmuch]]. - -** [[doom-module::email wanderlust][wanderlust]]: [[doom-module::email wanderlust +gmail][+gmail]] -: To boldly go where no mail has gone before - -#+begin_quote - 🔨 This module has no description. [[doom-contrib-module:][Write one?]] -#+end_quote - - -* [[doom-module::input][:input]] ({{{modules-in(input/*)}}}) -Modules in this category extend Emacs support for additional keyboard layouts -and input methods for non-English languages. - -** [[doom-module::input chinese][chinese]]: - -: Spend your 3 hours a week in Emacs - -This module adds support for traditional Chinese script by introducing two input -methods: Pinyin and Wubi. - -** [[doom-module::input japanese][japanese]]: - -: Ah, a man of culture - -This module adds support for Japanese script. - -** [[doom-module::input layout][layout]]: [[doom-module::input layout +azerty][+azerty]] [[doom-module::input layout +bepo][+bepo]] -: auie,ctsrnm is the superior home row - -This module provides barebones support for using Doom with non-qwerty keywoard -layouts. - - -* [[doom-module::lang][:lang]] ({{{modules-in(lang/*)}}}) -These modules specialize in integration particular languages and their -ecosystems into (Doom) Emacs. - -** [[doom-module::lang agda][agda]]: - -: Types of types of types of types... - -This module adds support for the [[http://wiki.portal.chalmers.se/agda/pmwiki.php][agda]] programming language. The Emacs support -exists directly in the agda repository but not in melpa. - -** [[doom-module::lang beancount][beancount]]: [[doom-module::lang beancount +lsp][+lsp]] -: Mind the GAAP - -This module adds support for [[https://beancount.github.io/][Beancount]] to Emacs. Beancount, like ledger, lets -you [[https://plaintextaccounting.org/][manage your money in plain text]]. - -** [[doom-module::lang cc][cc]]: [[doom-module::lang cc +lsp][+lsp]] -: C > C++ == 1 - -This module adds support for the C-family of languages: C, C++, and Objective-C. - -- Code completion (~company-irony~) -- eldoc support (~irony-eldoc~) -- Syntax-checking (~flycheck-irony~) -- Code navigation (~rtags~) -- File Templates ([[../../editor/file-templates/templates/c-mode][c-mode]], [[../../editor/file-templates/templates/c++-mode][c++-mode]]) -- Snippets ([[https://github.com/hlissner/doom-snippets/tree/master/cc-mode][cc-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c++-mode][c++-mode]]) -- Several improvements to C++11 indentation and syntax highlighting. - -** [[doom-module::lang clojure][clojure]]: [[doom-module::lang clojure +lsp][+lsp]] -: Java with a lisp - -This module adds support for the Clojure(Script) language. - -- Interactive development environment (~cider~): REPL, compilation, debugging, - running tests, definitions & documentation lookup, code completion, and much - more -- Refactoring (~clj-refactor~) -- Linting (~clj-kondo~), requires ~:checkers syntax~ -- LSP support (~clojure-lsp~) - -** [[doom-module::lang common-lisp][common-lisp]]: - -: If you've seen one lisp, you've seen them all - -This module provides support for [[https://lisp-lang.org/][Common Lisp]] and the [[doom-package:][Sly]] development -environment. Common Lisp is not a single language but a specification, with many -competing compiler implementations. By default, [[http://www.sbcl.org/][Steel Bank Common Lisp]] (SBCL) is -assumed to be installed, but this can be configured. - -Common Lisp benefits from a mature specification and rich standard library. -Thanks to its powerful REPL and debugger, it boasts an "interactive programming" -style often unseen in other languages. Compiled Common Lisp programs are trusted -to run unmodified for a long time. - -** [[doom-module::lang coq][coq]]: - -: Proofs as programs - -This module adds [[https://coq.inria.fr][coq]] support, powered by [[https://proofgeneral.github.io][Proof General]]. - -- Code completion ([[https://github.com/cpitclaudel/company-coq][company-coq]]) -- [[https://github.com/hlissner/doom-snippets/tree/master/coq-mode][Snippets]] - -** [[doom-module::lang crystal][crystal]]: - -: Ruby at the speed of c - -This modules adds [[https://crystal-lang.org/][crystal]] support. - -- Syntax-checking (~flycheck~) -- REPL (~inf-crystal~) - -** [[doom-module::lang csharp][csharp]]: [[doom-module::lang csharp +dotnet][+dotnet]] [[doom-module::lang csharp +lsp][+lsp]] [[doom-module::lang csharp +unity][+unity]] -: Unity, .NET, and mono shenanigans - -This module adds C# support to Emacs, powered by Omnisharp (directly or through -LSP). - -** [[doom-module::lang dart][dart]]: [[doom-module::lang dart +flutter][+flutter]] [[doom-module::lang dart +lsp][+lsp]] -: Paint ui and not much else - -[[https://dart.dev/][Dart]] is a client-optimized language by Google for fast apps on any platform. It -is fast and optimized for UI, famous for the [[https://flutter.io/][Flutter]] framework, also made by -Google. Both Flutter and Dart are free and open-source. - -This module wraps ~dart-mode~, with [[https://microsoft.github.io/language-server-protocol/][LSP]] features like code completion for -=.dart= files, syntax highlighting, debugging, closing labels, etc. - -** [[doom-module::lang data][data]]: - -: A dumping ground for data formats - -This module adds Emacs support for CSV and XML files. - -** [[doom-module::lang dhall][dhall]]: - -: Config as code - -This module adds [[https://dhall-lang.org/][Dhall]] language support to Emacs. - -Dhall is a programmable configuration language that you can think of as: JSON + -functions + types + imports. - -** [[doom-module::lang elixir][elixir]]: [[doom-module::lang elixir +lsp][+lsp]] -: Erlang done right - -This module provides support for [[https://elixir-lang.org/][Elixir programming language]] via [[doom-package:][alchemist]] or -[[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]]. - -** [[doom-module::lang elm][elm]]: [[doom-module::lang elm +lsp][+lsp]] -: Care for a cup of TEA? - -This module adds [[https://elm-lang.org/][Elm]] support to Doom Emacs. - -** [[doom-module::lang emacs-lisp][emacs-lisp]]: - -: A parsel-tongue for the oldest serpent - -This module extends support for Emacs Lisp in Doom Emacs. - -- Macro expansion -- Go-to-definitions or references functionality -- Syntax highlighting for defined and quoted symbols -- Replaces the built-in help with the more powerful [[doom-package:][helpful]] -- Adds function example uses to documentation - -** [[doom-module::lang erlang][erlang]]: [[doom-module::lang erlang +lsp][+lsp]] -: An elegant language for a more civilized age - -This module provides support [[https://www.erlang.org/][Erlang programming language]]. Support for the -[[https://github.com/erlang/sourcer][sourcer]] language server is optional. - -Includes: -- Code completion ([[doom-module:][+lsp]], [[doom-module:][:completion company]], & [[doom-module:][:completion ivy]]) -- Syntax checking ([[doom-module:][:checkers syntax]]) - -** [[doom-module::lang ess][ess]]: [[doom-module::lang ess +stan][+stan]] -: 73.6% of all statistics are made up - -This module adds support for various statistics languages, including R, S-Plus, -SAS, Julia and Stata. - -** [[doom-module::lang factor][factor]]: - -: ... - -This module adds support to the [[https://github.com/factor/factor][factor]] programming language and its associated -[[doom-package:][fuel]] emacs plugin. - -** [[doom-module::lang faust][faust]]: - -: DSP, but you get to keep your soul - -Add support to [[https://faust.grame.fr/][Faust language]] inside emacs. - -- Faust code syntax highlighting and indentation -- Project-based (inter-linked Faust files) -- Build/compile with output window -- Graphic diagrams generation and visualization in the (default) browser -- Browse generated C++ code inside Emacs -- Inter-linked files/buffers : - - From "component" to Faust file - - From "include" to Faust library file -- From error to file:line number -- From function name to online documentation -- Fully configurable (build type/target/architecture/toolkit, keyboard - shortcuts, etc.) -- Automatic keyword completion (if Auto-Complete is installed) -- Automatic objets (functions, operators, etc.) template insertion with default - sensible values (if [[doom-module:][:editor snippets]] is enabled) -- Modeline indicator of the state of the code - -** [[doom-module::lang fsharp][fsharp]]: [[doom-module::lang fsharp +lsp][+lsp]] -: ML stands for Microsoft's Language - -This module adds [[https://fsharp.org/][F#]] support to Doom Emacs. - -** [[doom-module::lang fstar][fstar]]: - -: (Dependent) types and (monadic) effects and Z3 - -This module adds [[https://fstar-lang.org/][F*]] support, powered by [[https://github.com/FStarLang/fstar-mode.el][fstar-mode.el]]. - -- Syntax highlighting -- Interactively process F* files one definition at a time -- Query the running F* process to look up definitions, documentation, and - theorems - -** [[doom-module::lang gdscript][gdscript]]: [[doom-module::lang gdscript +lsp][+lsp]] -: the language you waited for - -This module adds support for GDScript, the scripting language of the [[http://godotengine.org/][Godot]] game -engine, to Doom Emacs, powered by [[https://github.com/GDQuest/emacs-gdscript-mode][gdscript-mode]]. - -** [[doom-module::lang go][go]]: [[doom-module::lang go +lsp][+lsp]] -: The hipster dialect - -This module adds [[https://golang.org][Go]] support, with optional (but recommended) LSP support via -[[https://github.com/golang/tools/blob/master/gopls/README.md][gopls]]. - -- Code completion (~gocode~) -- Documentation lookup (~godoc~) -- Eldoc support (~go-eldoc~) -- REPL (~gore~) -- Syntax-checking (~flycheck~) -- Auto-formatting on save (~gofmt~) (requires [[doom-module:][:editor format +onsave]]) -- Code navigation & refactoring (~go-guru~) -- [[../../editor/file-templates/templates/go-mode][File templates]] -- [[https://github.com/hlissner/doom-snippets/tree/master/go-mode][Snippets]] -- Generate testing code (~go-gen-test~) -- Code checking (~flycheck-golangci-lint~) - -** [[doom-module::lang haskell][haskell]]: [[doom-module::lang haskell +lsp][+lsp]] -: A language that's lazier than I am - -This module adds Haskell support to Doom Emacs. - -** hy: - -/(No description)/ - -** [[doom-module::lang idris][idris]]: - -: A language you can depend on - -This module adds rudimentary Idris support to Doom Emacs. - -** [[doom-module::lang java][java]]: [[doom-module::lang java +lsp][+lsp]] [[doom-module::lang java +meghanada][+meghanada]] -: The poster child for carpal tunnel syndrome - -This module adds [[https://www.java.com][Java]] support to Doom Emacs, including ~android-mode~ and -~groovy-mode~. - -** [[doom-module::lang javascript][javascript]]: [[doom-module::lang javascript +lsp][+lsp]] -: all(hope(abandon(ye(who(enter(here)))))) - -This module adds JavaScript and TypeScript support. - -- Code completion ([[doom-package:][tide]]) -- REPL support ([[doom-package:][nodejs-repl]]) -- Refactoring commands ([[doom-package:][js2-refactor]]) -- Syntax checking ([[doom-package:][flycheck]]) -- Browser code injection with [[doom-package:][skewer-mode]] -- Coffeescript & JSX support -- Jump-to-definitions and references support ([[doom-package:][xref]]) - -** [[doom-module::lang json][json]]: [[doom-module::lang json +lsp][+lsp]] -: At least it ain't XML - -This module adds JSON support to Doom Emacs. - -** [[doom-module::lang julia][julia]]: [[doom-module::lang julia +lsp][+lsp]] -: A better, faster MATLAB - -This module adds support for [[https://julialang.org/][the Julia language]] to Doom Emacs. - -- Syntax highlighting and latex symbols from [[doom-package:][julia-mode]] -- REPL integration from [[doom-package:][julia-repl]] -- Code completion and syntax checking, requires [[doom-module:][:tools lsp]] and [[doom-module:][+lsp]] - -** [[doom-module::lang kotlin][kotlin]]: [[doom-module::lang kotlin +lsp][+lsp]] -: A Java(Script) that doesn't depress you - -This module adds [[https://kotlinlang.org/][Kotlin]] support to Doom Emacs. - -** [[doom-module::lang latex][latex]]: [[doom-module::lang latex +cdlatex][+cdlatex]] [[doom-module::lang latex +fold][+fold]] [[doom-module::lang latex +latexmk][+latexmk]] [[doom-module::lang latex +lsp][+lsp]] -: Writing papers in Emacs has never been so fun - -Provide a helping hand when working with LaTeX documents. - -- Sane defaults -- Fontification of many popular commands -- Pretty indentation of wrapped lines using the [[doom-package:][adaptive-wrap]] package -- Spell checking with [[doom-package:][flycheck]] -- Change PDF viewer to Okular or [[doom-package:][latex-preview-pane]] -- Bibtex editor -- Autocompletion using [[doom-package:][company-mode]] -- Compile your .tex code only once using LatexMk - -** [[doom-module::lang lean][lean]]: - -: For folks with too much to prove - -This module adds support for the [[https://leanprover.github.io/about/][Lean programming language]] to Doom Emacs. - -** [[doom-module::lang ledger][ledger]]: - -: Be audit you can be - -This module adds support for [[https://www.ledger-cli.org/][ledger]] files. Ledger is a command line double-entry -accounting system that works with simple text files holding transactions in the -following format: -#+begin_src ledger -2015/10/12 Exxon - Expenses:Auto:Gas $10.00 - Liabilities:MasterCard $-10.00 -#+end_src - -This modules enables the following features: -- Syntax and indentation support for ledger files -- Add, edit, and delete transactions -- Generate reports -- Schedule transactions -- Sort transactions -- Display statistics about transactions -- Display balance up to a point - -** [[doom-module::lang lua][lua]]: [[doom-module::lang lua +fennel][+fennel]] [[doom-module::lang lua +lsp][+lsp]] [[doom-module::lang lua +moonscript][+moonscript]] -: One-based indices? one-based indices - -This module adds Lua support to Doom Emacs. - -- REPL -- Love2D specific functions -- Moonscript support -- Fennel support - -** [[doom-module::lang markdown][markdown]]: [[doom-module::lang markdown +grip][+grip]] -: Write docs for people to ignore - -This module provides Markdown support for Emacs. - -#+begin_quote -Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you -to write using an easy-to-read, easy-to-write plain text format, then convert it -to structurally valid XHTML (or HTML). - -Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a -software tool, written in Perl, that converts the plain text formatting to HTML. -See the Syntax page for details pertaining to Markdown’s formatting syntax. You -can try it out, right now, using the online Dingus. - -The overriding design goal for Markdown’s formatting syntax is to make it as -readable as possible. The idea is that a Markdown-formatted document should be -publishable as-is, as plain text, without looking like it’s been marked up with -tags or formatting instructions. While Markdown’s syntax has been influenced by -several existing text-to-HTML filters, the single biggest source of inspiration -for Markdown’s syntax is the format of plain text email. -- John Gruber -#+end_quote - -** [[doom-module::lang nim][nim]]: - -: Python + lisp at the speed of C - -This module adds [[https://nim-lang.org][Nim]] support to Doom Emacs. - -- Code completion ([[doom-package:][nimsuggest]] + [[doom-package:][company]]) -- Syntax checking ([[doom-package:][nimsuggest]] + [[doom-package:][flycheck]]) -- Org babel support ([[doom-package:][ob-nim]]) - -** [[doom-module::lang nix][nix]]: - -: I hereby declare "nix geht mehr!" - -This module adds support for the Nix language to Doom Emacs, along with tools -for managing [[https://nixos.org/][Nix(OS)]]. - -Including: -- Syntax highlighting -- Completion through [[doom-package:][company]] and/or [[doom-package:][helm]] -- Nix option lookup -- Formatting (~nixfmt~) - -** [[doom-module::lang ocaml][ocaml]]: [[doom-module::lang ocaml +lsp][+lsp]] -: An objective camel - -This module adds [[https://ocaml.org/][OCaml]] support to Doom Emacs, powered by [[doom-package:][tuareg-mode]]. - -- Code completion, documentation look-up, code navigation and refactoring - ([[doom-package:][merlin]]) -- Type, documentation and function argument display on idle ([[doom-package:][merlin-eldoc]]) -- REPL ([[doom-package:][utop]]) -- Syntax-checking ([[doom-package:][merlin]] with [[doom-package:][flycheck-ocaml]]) -- Auto-indentation ([[doom-package:][ocp-indent]]) -- Code formatting ([[doom-package:][ocamlformat]]) -- Dune file format ([[doom-package:][dune]]) - -** [[doom-module::lang org][org]]: [[doom-module::lang org +brain][+brain]] [[doom-module::lang org +dragndrop][+dragndrop]] [[doom-module::lang org +gnuplot][+gnuplot]] [[doom-module::lang org +hugo][+hugo]] [[doom-module::lang org +ipython][+ipython]] [[doom-module::lang org +journal][+journal]] [[doom-module::lang org +jupyter][+jupyter]] [[doom-module::lang org +noter][+noter]] [[doom-module::lang org +pandoc][+pandoc]] [[doom-module::lang org +pomodoro][+pomodoro]] [[doom-module::lang org +present][+present]] [[doom-module::lang org +pretty][+pretty]] [[doom-module::lang org +roam][+roam]] [[doom-module::lang org +roam2][+roam2]] -: Organize your plain life in plain text - -This module adds org-mode support to Doom Emacs, along with a number of -adjustments, extensions and reasonable defaults to make it more performant and -intuitive out of the box: - -- A custom, centralized attachment system that stores files in one place, rather - than in the same directory as the input file(s) (only applies to attachments - from files in/under ~org-directory~). -- Executable code blocks with support for a variety of languages and tools - (depending on what :lang modules are enabled). -- Supports an external org-capture workflow through the =bin/org-capture= shell - script and ~+org-capture/open-frame~. -- A configuration for using org-mode for slide-show presentations or exporting - org files to reveal.js slideshows. -- Drag-and-drop support for images (with inline preview) and media files (drops - a file icon and a short link) (requires [[doom-module:][+dragndrop]] flag). -- Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others - (requires flags). -- Export-to-clipboard functionality, for copying text into formatted html, - markdown or rich text to the clipboard (see ~+org/export-to-clipboard~ and - ~+org/export-to-clipboard-as-rich-text~). - -#+begin_quote -Org is a system for writing plain text notes with syntax highlighting, code -execution, task scheduling, agenda management, and many more. The whole idea is -that you can write notes and mix them with references to things like articles, -images, and example code combined with the output of that code after it is -executed. - -https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode/ -#+end_quote - -** [[doom-module::lang php][php]]: [[doom-module::lang php +hack][+hack]] [[doom-module::lang php +lsp][+lsp]] -: Perl's insecure younger brother - -This module adds support for PHP 5.3+ (including PHP7) to Doom Emacs. - -- ctags-based code completion (~company-php~ and ~phpctags~) -- eldoc support (~ac-php~ and ~php-extras~) -- REPL (~php-boris~) -- Code refactoring commands (~php-refactor-mode~) -- Unit-test commands (~phpunit~) -- Support for ~laravel~ and ~composer~ projects (with project-specific snippets) -- [[../../editor/file-templates/templates/php-mode][File templates]] -- [[https://github.com/hlissner/doom-snippets/tree/master/php-mode][Snippets]] - -#+begin_quote - 💡 PHP was the first programming language I got paid to code in, back in the - Cretaceous period (2003). My sincerest apologies go out to all the - programmers who inherited my earliest PHP work. I know you're out there, - writhing in your straitjackets. - - Save a programmer today. Stop a friend from choosing PHP as their first - language. -#+end_quote - -** [[doom-module::lang plantuml][plantuml]]: - -: Diagrams to confuse people more - -This module adds plantuml support to Emacs; allowing you to generate diagrams -from plain text. - -** [[doom-module::lang purescript][purescript]]: [[doom-module::lang purescript +lsp][+lsp]] -: Javascript, but functional - -This module adds [[https://www.purescript.org/][Purescript]] support to Doom Emacs. - -** [[doom-module::lang python][python]]: [[doom-module::lang python +conda][+conda]] [[doom-module::lang python +cython][+cython]] [[doom-module::lang python +lsp][+lsp]] [[doom-module::lang python +poetry][+poetry]] [[doom-module::lang python +pyenv][+pyenv]] [[doom-module::lang python +pyright][+pyright]] -: Beautiful is better than ugly - -This module adds [[https://www.python.org/][Python]] support to Doom Emacs. - -- Syntax checking ([[doom-package:][flycheck]]) -- Snippets -- Run tests ([[doom-package:][nose]], [[doom-package:][pytest]]) -- Auto-format (with ~black~, requires [[doom-module:][:editor format]]) -- LSP integration (=mspyls=, =pyls=, or =pyright=) - -** [[doom-module::lang qt][qt]]: - -: The cutest GUI framework ever - -This module provides language functionality for [[https://qt.io][Qt]] specific files. - -- Syntax highlighting for [[https:://en.wikipedia.org/wiki/QML][qml]] files -- Syntax highlighting for =.pro= and =.pri= files used by [[https://doc.qt.io/qt-5/qmake-project-files.html][qmake]] - -** [[doom-module::lang racket][racket]]: [[doom-module::lang racket +lsp][+lsp]] [[doom-module::lang racket +xp][+xp]] -: The DSL for DSLs - -This module adds support for the [[https://www.racket-lang.org/][Racket programming language]] to Doom Emacs. - -** [[doom-module::lang raku][raku]]: - -: The artist formerly known as perl6 - -This module adds support for the [[https://www.raku.org/][Raku programming language]] to Doom Emacs. - -** [[doom-module::lang rest][rest]]: - -: Emacs as a REST client - -This module turns Emacs into a [[https://en.wikipedia.org/wiki/Representational_state_transfer][REST]] client. - -- Code-completion (~company-restclient~) -- Code evaluation -- Imenu support for ~restclient-mode~ -- org-mode: babel support (~ob-restclient~) - -#+begin_quote - 💡 ~restclient-mode~ is tremendously useful for automated or quick testing REST - APIs. My workflow is to open an ~org-mode~ buffer, create a restclient - source block and hack away. ~restclient-mode~ and ~company-restclient~ power - this arcane wizardry. -#+end_quote - -** [[doom-module::lang rst][rst]]: - -: ReST in peace - -This module adds [[https://docutils.sourceforge.io/rst.html][ReStructured Text]] support to Doom Emacs. - -** [[doom-module::lang ruby][ruby]]: [[doom-module::lang ruby +chruby][+chruby]] [[doom-module::lang ruby +lsp][+lsp]] [[doom-module::lang ruby +rails][+rails]] [[doom-module::lang ruby +rbenv][+rbenv]] [[doom-module::lang ruby +rvm][+rvm]] -: 1.step {|i| p "Ruby is #{i.even? ? 'love' : 'life'}"} - -This module add Ruby and optional Ruby on Rails support to Emacs. - -- Code completion ([[doom-package:][robe]]) -- Syntax checking ([[doom-package:][flycheck]]) -- Jump-to-definitions ([[doom-package:][robe]]) -- Bundler -- Rubocop integration ([[doom-package:][flycheck]]) - -** [[doom-module::lang rust][rust]]: [[doom-module::lang rust +lsp][+lsp]] -: Fe2O3.unwrap().unwrap().unwrap().unwrap() - -This module adds support for the Rust language and integration for its tools, -e.g. ~cargo~. - -+ Code completion (=racer= or an LSP server) -+ Syntax checking (=flycheck=) -+ LSP support (for rust-analyzer and rls) (=rustic=) -+ Snippets - -** [[doom-module::lang scala][scala]]: [[doom-module::lang scala +lsp][+lsp]] -: Java, but good - -This module adds [[https://www.scala-lang.org][scala]] and [[https://www.scala-sbt.org/][sbt]] support to Doom Emacs. - -Through the power of [[https://scalameta.org/metals/docs/editors/overview.html][Metals]] (LSP) this module offers: -- Goto Definition -- Completions -- Hover -- Paremeter Hints -- Find References -- Run/Debug -- Find Implementations -- Rename Symbol -- Code Actions -- Document Symbols -- Formatting -- Folding -- Organize Imports - -** [[doom-module::lang scheme][scheme]]: [[doom-module::lang scheme +chez][+chez]] [[doom-module::lang scheme +chibi][+chibi]] [[doom-module::lang scheme +chicken][+chicken]] [[doom-module::lang scheme +gambit][+gambit]] [[doom-module::lang scheme +gauche][+gauche]] [[doom-module::lang scheme +guile][+guile]] [[doom-module::lang scheme +kawa][+kawa]] [[doom-module::lang scheme +mit][+mit]] [[doom-module::lang scheme +racket][+racket]] -: A fully conniving family of lisps - -This module provides support for the Scheme family of Lisp languages, powered by -[[https://www.nongnu.org/geiser/geiser_1.html#introduction][geiser]]. - -** [[doom-module::lang sh][sh]]: [[doom-module::lang sh +fish][+fish]] [[doom-module::lang sh +lsp][+lsp]] [[doom-module::lang sh +powershell][+powershell]] -: She sells {ba,z,fi}sh shells on the C xor - -This module adds support for shell scripting languages (including Powershell and -Fish script) to Doom Emacs. - -- Code completion ([[doom-package:][company-shell]]) -- Syntax Checking ([[doom-package:][flycheck]]) - -** [[doom-module::lang sml][sml]]: - -: ... - -THis module adds [[https://smlfamily.github.io/][SML (Standard ML) programming language]] support to Doom Emacs. - -** [[doom-module::lang solidity][solidity]]: - -: Do you need a blockchain? No. - -This module adds [[https://github.com/ethereum/solidity][Solidity]] support to Doom Emacs. - -- Syntax-checking ([[doom-package:][flycheck]]) -- Code completion ([[doom-package:][company-solidity]]) -- Gas estimation (~C-c C-g~) - -** [[doom-module::lang swift][swift]]: [[doom-module::lang swift +lsp][+lsp]] -: We asked for emoji variables? - -This module adds support for the [[https://developer.apple.com/swift/][Swift programming language]] to Doom Emacs. - -** [[doom-module::lang terra][terra]]: - -: Earth and Moon in alignment for performance. - -\(No description yet\) - -** [[doom-module::lang web][web]]: - -: The tubes - -This module adds support for various web languages, including HTML5, CSS, -SASS/SCSS, Pug/Jade/Slim, and HAML, as well as various web frameworks, like -ReactJS, Wordpress, Jekyll, Phaser, AngularJS, Djano, and more. - -** [[doom-module::lang yaml][yaml]]: [[doom-module::lang yaml +lsp][+lsp]] -: JSON, but readable - -This module provides support for the [[https://yaml.org/][YAML file format]] to Doom Emacs. - -** [[doom-module::lang zig][zig]]: [[doom-module::lang zig +lsp][+lsp]] -: C, but simpler - -This module adds [[https://ziglang.org/][Zig]] support, with optional (but recommended) LSP support via -[[https://github.com/zigtools/zls][zls]]. - -- Syntax highlighting -- Syntax-checking ([[doom-package:][flycheck]]) -- Code completion and LSP integration (~zls~) - - -* :os -/(No description)/ - -** [[doom-module::os macos][macos]]: - -: Compatibility for our favorite walled garden - -This module provides extra functionality for macOS. - -** [[doom-module::os tty][tty]]: [[doom-module::os tty +osc][+osc]] -: Make TTY Emacs suck less - -This module configures Emacs for use in the terminal, by providing: - -- System clipboard integration (through an external clipboard program or OSC-52 - escape codes in supported terminals). -- Cursor-shape changing across evil states (requires a terminal that supports - it). -- Mouse support in the terminal. - - -* [[doom-module::term][:term]] ({{{modules-in(term/*)}}}) -What's an operating system without a terminal? The modules in this category -bring varying degrees of terminal emulation into Emacs. - -If you can't decide which to choose, I recommend [[doom-package:][vterm]] or [[doom-package:][eshell]]. [[doom-module:][:term vterm]] -offers that best terminal emulation available but requires a few extra steps to -get going. [[doom-module:][:term eshell]] works everywhere that Emacs runs, even Windows, and -provides a shell entirely implemented in Emacs Lisp. - -** [[doom-module::term eshell][eshell]]: - -: The elisp shell that works everywhere - -This module provides additional features for the built-in [[https://www.gnu.org/software/emacs/manual/html_mono/eshell.html][Emacs Shell]] - -The Emacs Shell or [[doom-package:][eshell]] is a shell-like command interpreter implemented in -Emacs Lisp. It is an alternative to traditional shells such as =bash=, =zsh=, -=fish=, etc. that is built into Emacs and entirely cross-platform. - -** [[doom-module::term shell][shell]]: - -: A REPL for your shell - -Provides a REPL for your shell. - -#+begin_quote - 💡 =shell= is more REPL than terminal emulator. You can edit your command line - like you would any ordinary text in Emacs -- something you can't do in [[doom-package:][term]] - (without ~term-line-mode~, which can be unstable) or [[doom-package:][vterm]]. - - Due to =shell='s simplicity, you're less likely to encounter edge cases - (e.g. against your shell config), but it's also the least capable. TUI - programs like =htop= or =vim= won't work in shell directly, but will be - launched in a =term= buffer -- which handles them reasonably well. -#+end_quote - -** [[doom-module::term term][term]]: - -: It's terminal - -/(No description)/ - -** [[doom-module::term vterm][vterm]]: - -: As good as terminal emulation gets in Emacs - -This module provides a terminal emulator powered by libvterm. It is still in -alpha and requires a component be compiled (=vterm-module.so=). - -#+begin_quote - 💡 [[doom-package:][vterm]] is as good as terminal emulation gets in Emacs (at the time of - writing) and the most performant, as it is implemented in C. However, it - requires extra steps to set up: - - - Emacs must be built with dynamic modules support, - - and =vterm-module.so= must be compiled, which depends on =libvterm=, - =cmake=, and =libtool-bin=. - - [[doom-package:][vterm]] will try to automatically build =vterm-module.so= when you first open - it, but this will fail on Windows, NixOS and Guix out of the box. Install - instructions for nix/guix can be found in the [[doom-module:][:term vterm]] module’s - documentation. There is no way to install vterm on Windows that I’m aware of - (but perhaps with WSL?). -#+end_quote - - -* [[doom-module::tools][:tools]] ({{{modules-in(tools/*)}}}) -Modules that integration external tools into Emacs. - -** [[doom-module::tools ansible][ansible]]: - -: Allow silly people to focus on silly things - -/(No description)/ - -** biblio: - -/(No description)/ - -** [[doom-module::tools debugger][debugger]]: [[doom-module::tools debugger +lsp][+lsp]] -: Step through code to help you add bugs - -Introduces a code debugger to Emacs, powered by [[doom-package:][realgud]] or [[doom-package:][dap-mode]] (LSP). - -This document will help you to configure [[https:emacs-lsp.github.io/dap-mode/][dap-mode]] [[https://emacs-lsp.github.io/dap-mode/page/configuration/#native-debug-gdblldb][Native Debug(GDB/LLDB)]] as -there is still not *enough* documentation for it. - -** [[doom-module::tools direnv][direnv]]: - -: Save (or destroy) the environment at your leisure - -This module integrates direnv into Emacs. - -#+begin_quote - 📌 direnv is an environment switcher for the shell. It knows how to hook into - bash, zsh, tcsh, fish shell and elvish to load or unload environment - variables depending on the current directory. This allows project-specific - environment variables without cluttering the ~/.profile file. - - Before each prompt, direnv checks for the existence of a ".envrc" file in - the current and parent directories. If the file exists (and is authorized), - it is loaded into a bash sub-shell and all exported variables are then - captured by direnv and then made available to the current shell. -#+end_quote - -** [[doom-module::tools docker][docker]]: [[doom-module::tools docker +lsp][+lsp]] -: Yo dawg, I heard you like OSes, so I… - -This module allows you to manipulate Docker images, containers, and more from -Emacs. - -Provides a major ~dockerfile-mode~ to edit =Dockerfiles=. Additional convenience -functions allow images to be built easily. - -[[doom-package:][docker-tramp]] offers [[https://www.gnu.org/software/tramp/][TRAMP]] support for Docker containers. - -** [[doom-module::tools editorconfig][editorconfig]]: - -: Someone else can argue about tabs and spaces - -This module integrates [[https://editorconfig.org/][EditorConfig]] into Emacs, allowing users to dictate code -style on a per-project basis with an =.editorconfig= file ([[https://editorconfig-specification.readthedocs.io/][formal -specification]]). - -** [[doom-module::tools ein][ein]]: - -: Tame Jupyter notebooks with emacs - -Adds [[https://jupyter.org/][Jupyter]] notebook integration into Emacs. - -** [[doom-module::tools eval][eval]]: [[doom-module::tools eval +overlay][+overlay]] -: Run code, run (also, repls) - -This modules adds inline code evaluation support to Emacs and a universal -interface for opening and interacting with REPLs. - -** [[doom-module::tools gist][gist]]: - -: A pastebin for Githubsters - -Adds the ability to manage, pull from, or push to your [[https://gist.github.com][Gists]] from within Emacs. - -** [[doom-module::tools lookup][lookup]]: [[doom-module::tools lookup +dictionary][+dictionary]] [[doom-module::tools lookup +docsets][+docsets]] [[doom-module::tools lookup +offline][+offline]] -: Navigate your labyrinthine code and docs - -This module adds code navigation and documentation lookup tools to help you -quickly look up definitions, references, documentation, dictionary definitions -or synonyms. - -- Jump-to-definition and find-references implementations that just work. -- Powerful xref integration for languages that support it. -- Search online providers like [[https://devdocs.io][devdocs.io]], [[https://stackoverflow.com][stackoverflow]], [[https://google.com][google]], [[https://duckduckgo.com][duckduckgo]], or - [[https://youtube.com][youtube]] (duckduckgo and google have live suggestions). -- Integration with [[https://github.com/Kapeli/feeds][Dash.app docsets]]. -- Support for online (and offline) dictionaries and thesauruses. - -** [[doom-module::tools lsp][lsp]]: [[doom-module::tools lsp +eglot][+eglot]] [[doom-module::tools lsp +peek][+peek]] -: M-x vscode - -This module integrates [[https://langserver.org/][language servers]] into Doom Emacs. They provide features -you'd expect from IDEs, like code completion, realtime linting, language-aware -[[doom-package:][imenu]]/[[doom-package:][xref]] integration, jump-to-definition/references support, and more. - -As of this writing, this is the state of LSP support in Doom Emacs: - -| Module | Major modes | Default language server | -|------------------+---------------------------------------------------------+---------------------------------------------------------------| -| [[doom-module:][:lang cc]] | c-mode, c++-mode, objc-mode | ccls, clangd | -| [[doom-module:][:lang clojure]] | clojure-mode | clojure-lsp | -| [[doom-module:][:lang csharp]] | csharp-mode | omnisharp | -| [[doom-module:][:lang elixir]] | elixir-mode | elixir-ls | -| [[doom-module:][:lang fsharp]] | fsharp-mode | Mono, .NET core | -| [[doom-module:][:lang go]] | go-mode | go-langserver | -| [[doom-module:][:lang haskell]] | haskell-mode | haskell-language-server | -| [[doom-module:][:lang java]] | java-mode | lsp-java | -| [[doom-module:][:lang javascript]] | js2-mode, rjsx-mode, typescript-mode | ts-ls, deno-ls | -| [[doom-module:][:lang julia]] | julia-mode | LanguageServer.jl | -| [[doom-module:][:lang ocaml]] | tuareg-mode | ocaml-language-server | -| [[doom-module:][:lang php]] | php-mode | php-language-server | -| [[doom-module:][:lang purescript]] | purescript-mode | purescript-language-server | -| [[doom-module:][:lang python]] | python-mode | lsp-python-ms | -| [[doom-module:][:lang ruby]] | ruby-mode | solargraph | -| [[doom-module:][:lang rust]] | rust-mode | rls | -| [[doom-module:][:lang scala]] | scala-mode | metals | -| [[doom-module:][:lang sh]] | sh-mode | bash-language-server | -| [[doom-module:][:lang swift]] | swift-mode | sourcekit | -| [[doom-module:][:lang web]] | web-mode, css-mode, scss-mode, sass-mode, less-css-mode | vscode-css-languageserver-bin, vscode-html-languageserver-bin | -| [[doom-module:][:lang zig]] | zig-mode | zls | - -** [[doom-module::tools magit][magit]]: [[doom-module::tools magit +forge][+forge]] -: Wield git like a wizard - -This module provides Magit, an interface to the Git version control system. - -** [[doom-module::tools make][make]]: - -: The discount build system - -This module adds commands for executing Makefile targets. - -** [[doom-module::tools pass][pass]]: [[doom-module::tools pass +auth][+auth]] -: A password manager for nerds - -This module provides an Emacs interface to [[https://www.passwordstore.org/][Pass]]. - -** [[doom-module::tools pdf][pdf]]: - -: Emacs, your next PDF reader - -This module improves support for reading and interacting with PDF files in -Emacs. - -It uses [[doom-package:][pdf-tools]], which is a replacement for the built-in ~doc-view-mode~ for -PDF files. The key difference being pages are not pre-rendered, but instead -rendered on-demand and stored in memory; a much faster approach, especially for -larger PDFs. - -Displaying PDF files is just one function of [[doom-package:][pdf-tools]]. See [[https://github.com/politza/pdf-tools][its project website]] -for details and videos. - -** [[doom-module::tools prodigy][prodigy]]: - -: No sweatshop is complete without child processes - -This module provides an interface for managing external services from within -Emacs. - -** [[doom-module::tools rgb][rgb]]: - -: Creating color strings - -Highlights color hex values and names with the color itself, and provides tools -to easily modify color values or formats. - -** [[doom-module::tools taskrunner][taskrunner]]: - -: Taskrunner for all your projects - -This module integrates [[doom-package:][taskrunner]] into Doom Emacs, which scraps runnable tasks -from build systems like make, gradle, npm and the like. - -** [[doom-module::tools terraform][terraform]]: - -: Infrastructure as code - -This module adds support for working with [[https://www.terraform.io][Terraform]] files within Emacs. This -includes syntax highlighting, intelligent code completion, and the ability to -run Terraform commands directly from Emacs. - -** [[doom-module::tools tmux][tmux]]: - -: From one multiplexer to another - -This module provides an API for talking to Tmux sessions. - -** [[doom-module::tools upload][upload]]: - -: Map local directories to remotes via ssh/ftp - -Uses ~ssh-deploy~ to map a local folder to a remote one. - -From the [[https://github.com/cjohansson/emacs-ssh-deploy/blob/master/README.md][ssh-deploy README]]: -#+begin_quote -The ssh-deploy plug-in for Emacs makes it possible to effortlessly deploy local files and directories to remote hosts via Tramp (including but not limited to SSH, SFTP, FTP). It tries to provide functions that can be easily used by custom scripts. - -The idea for this plug-in was to mimic the behavior of PhpStorm deployment functionality. -#+end_quote - - -* [[doom-module::ui][:ui]] ({{{modules-in(ui/*)}}}) -For modules concerned with changing Emacs' appearance or providing interfaces -for its features, like sidebars, tabs, or fonts. - -** [[doom-module::ui deft][deft]]: - -: Notational velocity for Emacs - -[[https://jblevins.org/projects/deft/][Deft]] is a major mode for creating, browsing, and filtering notes written in -plain text formats, such as org-mode, markdown, and LaTeX. It enables you to -quickly jot down thoughts and easily retrieve them later. - -** [[doom-module::ui doom][doom]]: - -: Make Doom fabulous again - -This module gives Doom its signature look: powered by the [[doom-package:doom-themes][doom-one]] theme -(loosely inspired by [[https://github.com/atom/one-dark-syntax][Atom's One Dark theme]]) and [[doom-package:][solaire-mode]]. Includes: - -- A custom folded-region indicator for ~hideshow~. -- "Thin bar" fringe bitmaps for ~git-gutter-fringe~. -- File-visiting buffers are slightly brighter (thanks to [[doom-package:][solaire-mode]]). - -** [[doom-module::ui doom-dashboard][doom-dashboard]]: - -: Welcome to your doom - -This module adds a minimalistic, Atom-inspired dashboard to Emacs. - -Besides eye candy, the dashboard serves two other purposes: - -1. To improve Doom's startup times (the dashboard is lighter than the scratch - buffer in many cases). - -2. And to preserve the "last open directory" you were in. Occasionally, I kill - the last buffer in my project and I end up who-knows-where (in the working - directory of another buffer/project). It can take some work to find my way - back to where I was. Not with the Dashboard. - - Since the dashboard cannot be killed, and it remembers the working directory - of the last open buffer, ~M-x find-file~ will work from the directory I - expect. - -** [[doom-module::ui doom-quit][doom-quit]]: - -: One does not simply quit Emacs - -A silly module that throws cute confirmation prompts at you when you exit Emacs, -like DOOM (the game) did. Some quotes are from the classic games, others are -random, nerdy references that no decent human being has any business -recognizing. - -** [[doom-module::ui emoji][emoji]]: [[doom-module::ui emoji +ascii][+ascii]] [[doom-module::ui emoji +github][+github]] [[doom-module::ui emoji +unicode][+unicode]] -: 💩 - -This module gives Emacs the ability to display and insert emojis (ASCII, Github -style, or unicode styles), as well as convert certain text patterns (e.g. -=:smile:=) into emojis. - -** [[doom-module::ui hl-todo][hl-todo]]: - -: TODO FIXME NOTE DEPRECATED HACK REVIEW - -This module adds syntax highlighting for various tags in code comments, such as -=TODO=, =FIXME=, and =NOTE=, among others. - -** [[doom-module::ui hydra][hydra]]: - -: Discount modality for mythological beast hunters - -This module adds hydra to Doom Emacs, as well as a few custom built hydras to -start with: - -- A hydra to control windows ~+hydra/window-nav/body~. -- A hydra to control text zoom level ~+hydra/text-zoom/body~. - -** [[doom-module::ui indent-guides][indent-guides]]: - -: Line up them indent columns - -\(No description yet\) - -** [[doom-module::ui ligatures][ligatures]]: [[doom-module::ui ligatures +extra][+extra]] -: Distract folks from your code - -This module enables ligatures and arbitrary symbol substitutions with -~mac-auto-operator-composition-mode~ (on supported macOS systems) or composition -tables (harfbuzz on Emacs 28), falling back on ~prettify-symbols-mode~ -otherwise. - -** [[doom-module::ui minimap][minimap]]: - -: A map for lost programmers - -This module displays a minimap of the buffer in a sidebar, similar to the -feature found in many other editors. - -** [[doom-module::ui modeline][modeline]]: [[doom-module::ui modeline +light][+light]] -: Snazzy, Atom-inspired modeline, plus API - -This module provides an Atom-inspired, minimalistic modeline for Doom Emacs, -powered by the [[doom-package:][doom-modeline]] package (where you can find screenshots). - -** [[doom-module::ui nav-flash][nav-flash]]: - -: Blink after big motions - -This module flashes the line around the cursor after any significant motion, to -make it easy to follow after big operations. - -#+begin_quote - 💡 Tremendously helpful on large, 1600p+ or 4K displays. -#+end_quote - -** [[doom-module::ui neotree][neotree]]: - -: NERDTree for evil nerds - -This module brings a side panel for browsing project files, inspired by vim's -NERDTree. - -#+begin_quote - 💡 Sure, there's [[doom-package:][dired]] and [[doom-package:][projectile]], but sometimes I'd like a bird's eye view - of a project. -#+end_quote - -** [[doom-module::ui ophints][ophints]]: - -: An indicator for “what did I just do?” - -This module provides op-hints (operation hinting), i.e. visual feedback for -certain operations. It highlights regions of text that the last operation (like -yank) acted on. - -Uses [[doom-package:][evil-goggles]] for evil users and [[doom-package:][volatile-highlights]] otherwise. - -** [[doom-module::ui popup][popup]]: [[doom-module::ui popup +all][+all]] [[doom-module::ui popup +defaults][+defaults]] -: Tame sudden yet inevitable temporary windows - -This module provides a customizable popup window management system. - -Not all windows are created equally. Some are less important. Some I want gone -once they have served their purpose, like code output or a help buffer. Others I -want to stick around, like a scratch buffer or org-capture popup. - -More than that, popups ought to be the second class citizens of my editor; -spawned off to the side, discarded with the push of a button (e.g. [[kbd:][ESC]] or [[kbd:][C-g]]), -and easily restored if I want to see them again. Of course, this system should -clean up after itself and kill off buffers I mark as transient. - -** [[doom-module::ui tabs][tabs]]: - -: Keep tabs on your buffers, literally - -This module adds an Atom-esque tab bar to the Emacs UI. - -** [[doom-module::ui treemacs][treemacs]]: [[doom-module::ui treemacs +lsp][+lsp]] -: A project drawer like neotree but cooler - -[[https://github.com/Alexander-Miller/treemacs][Treemacs]] is a file and project explorer similar to NeoTree or vim’s NerdTree, -but largely inspired by the Project Explorer in Eclipse. It shows the file -system outlines of your projects in a simple tree layout allowing quick -navigation and exploration, while also possessing basic file management -utilities. It includes: - -- Integration with Git (when [[doom-module:][:tools magit]] is enabled) -- Integration with Evil (when [[doom-module:][:editor evil +everywhere]] is enabled) -- Workspace awareness (when [[doom-module:][:ui workspaces]] is enabled) - -** [[doom-module::ui unicode][unicode]]: - -: Extended unicode support for various languages - -This module extends Doom's ability to display non-English unicode. It is -primarily useful for non-English Emacs users, for whom Doom's built-in unicode -support in insufficient. - -This module relies on the [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] package. It tries to setup the default -emacs fontset to cover as many unicode glyphs as possible by scanning all -available glyphs from all available fonts. - -When this module is enabled: -- Emacs will prefer to use the ~doom-unicode-font~ font to display non-latin - glyphs if it provides coverage for them. -- The first time you run Emacs a unicode cache will be generated -- this will - take a while! -- The cache will be regenerated every time Emacs is made aware of new fonts or - you change the font configuration e.g. by modifying ~doom-unicode-font~. -- The cache will be stored and should not be regenerated unless font-related - configuration or the versions of relevant packages changes. - -** [[doom-module::ui vc-gutter][vc-gutter]]: - -: Get your diff out of the gutter - -This module displays a diff of the current file (against HEAD) in the fringe. -Supports Git, Svn, Hg, and Bzr. - -** [[doom-module::ui vi-tilde-fringe][vi-tilde-fringe]]: - -: Fringe tildes beyond EOB - -Displays a tilde(~) in the left fringe to indicate an empty line, similar to Vi. - -** [[doom-module::ui window-select][window-select]]: [[doom-module::ui window-select +numbers][+numbers]] [[doom-module::ui window-select +switch-window][+switch-window]] -: Visually switch windows - -This module provides several methods for selecting windows without the use of -the mouse or spatial navigation (e.g. [[kbd:][C-w {h,j,k,l}]]). - -The command ~other-window~ is remapped to either [[doom-package:][switch-window]] or [[doom-package:][ace-window]], -depending on which backend you've enabled. It is bound to [[kbd:][C-x o]] (and [[kbd:][C-w C-w]] for -evil users). - -It also provides numbered windows and selection with the [[doom-package:][winum]] package, if -desired. Evil users can jump to window N in [[kbd:][C-w ]] (where N is a number between -0 and 9). Non evil users have [[kbd:][C-x w ]] instead. - -** [[doom-module::ui workspaces][workspaces]]: - -: Tab emulation, persistence, & separate workspaces - -This module adds support for workspaces, powered by [[doom-package:][persp-mode]], as well as a API -for manipulating them. - -#+begin_quote - 💡 There are many ways to use workspaces. I spawn a workspace per task. Say I'm - working in the main workspace, when I realize there is a bug in another part - of my project. I open a new workspace and deal with it in there. In the - meantime, I need to check my email, so mu4e gets its own workspace. - - Once I've completed the task, I close the workspace and return to main. -#+end_quote - -** [[doom-module::ui zen][zen]]: - -: Distraction-free mode for the eternally distracted - -This module provides two minor modes that make Emacs into a more comfortable -writing or coding environment. Folks familiar with "distraction-free" or "zen" -modes from other editors -- or [[doom-package:][olivetti]], [[doom-package:][sublimity]], and [[doom-package:][tabula-rasa]] (Emacs -plugins) -- will feel right at home. - -These modes are: -- ~mixed-pitch-mode~ :: - Which renders (most) text in a variable pitch font (see - ~doom-variable-pitch-font~). Unlike ~variable-pitch-mode~, this will not - affect segments of text that are intended to remain in a fixed pitch font, - such as code blocks or ASCII tables. -- ~writeroom-mode~ :: - Our all-in-one "zen" mode that will: - 1. Center the current buffer. - 2. Remove superfluous UI elements (like the modeline). - 3. Activate ~mixed-pitch-mode~. - 4. Scale up the buffer's text slightly (see ~+zen-text-scale~). - 5. And make the window's borders slightly thicker (see - ~+zen-window-divider-size~). - - -