DOOMDIR

Table of Contents

• Description
  • Maintainers
  • Module Flags
    • Discussion
  • Plugins
  • Hacks
• Prerequisites
• Features
  • Literate configuration
  • Doom Emacs documentation
• Configuration
  • Finding a good subtree in config.org for new configuration
  • Local configuration
• Troubleshooting
  • Finding an LSP server for a language
  • Trouble with tangling source blocks from =config.org=
  • =doom doctor= reports stale .elc files

Description

In Doom Emacs, one’s private configuration directory is technically a module, mostly (but not quite exactly) like any other module (e.g. :lang org), so I’ve decided to document mine as such.

For more detailed information on how modules should be structured, see the Writing your own modules section of Doom Emacs documentation.

Maintainers

• @eeowaa (Author)

Module Flags

This module provides no flags.

Discussion

DOOMDIR can’t really have module flags, since module flags are passed to module declarations in the doom! block, which is contained in DOOMDIR itself.

Plugins

In addition to all the packages installed by enabled modules in init.el (including custom modules in the modules/ directory), additional packages are installed via package! forms in packages.el.

Hacks

• Overridden function definitions via :override advice in config.el.
• Overridden use-package! forms via use-package-hook! forms in early-init.el.
• Modified doom-* theme(s) in themes/.

Prerequisites

System-specific shell scripts to install prerequisites are tangled from config.org into the install/ directory. The install/run script wraps all of these and may be used on any supported system (currently macOS and Fedora):

install/run

Features

Literate configuration

The following files are tangled from source blocks in config.org:

• config.el
• early-init.el
• packages.el
• install/*
• snippets/*

The following files are not currently tangled from config.org, but I have plans to port their contents to a literate config:

• init.el

All other files in DOOMDIR are probably “illiterate” for a reason; this is not subject to change anytime soon.

Doom Emacs documentation

See the docs/ directory for (currently work-in-progress) documentation I’ve written about Doom Emacs usage.

Configuration

Finding a good subtree in config.org for new configuration

config.org has been organized to mirror the structure of init.el, which in turn mirrors the structure of ~/.emacs.d/modules. Configuration for options, hooks, etc. in config.org should be done in the subtree which corresponds to the Doom module that performs configuration on related options, hooks, etc.

Use SPC h d e (my/doom-help-search-source) and SPC h d M (my/doom-help-search-modules) to find the module that contains configuration for (or in some cases, is at least intended to contain configuration for) the option, hook, etc. that you want to configure.

Local configuration

DOOMDIR/custom.el is ignored by .gitignore, so it is a good place to store most local configuration. You can take a look at the “Load custom config if present” section of config.org for an idea of what to put in it.

All credentials should go in some authentication source available to the auth-source library (check the auth-sources variable for what is configured locally).

Troubleshooting

Finding an LSP server for a language

Look for lsp-dependency forms in the lsp-mode library, specifically under ~/.emacs.d/.local/straight/repos/lsp-mode/clients/lsp-LANG.el for a given language. For example, lsp-json.el contains the following form:

(lsp-dependency 'vscode-json-languageserver
                '(:system "vscode-json-language-server")
                '(:npm :package "vscode-langservers-extracted"
                       :path "vscode-json-language-server"))

What this says is that if there is a vscode-json-language-server executable in your $PATH, then use that. Otherwise, prompt the user to install the vscode-langservers-extracted package using npm, which should install an executable named vscode-json-language-server (the lack of an absolute path means that the executable could be installed anywhere).

Trouble with tangling source blocks from config.org

Are you having trouble tangling config.org via C-c C-v C-t (org-babel-tangle)? Have you recently updated Doom Emacs using doom upgrade? If so, try running M-x pdf-tools-install before tangling config.org again.

doom doctor reports stale .elc files

If you see <package>/<file>.elc is out-of-date messages in the output of doom doctor, just remove the <package> directory and run doom sync:

$ doom doctor
(...)
> Checking for stale elc files...
! ~/.config/emacs/.local/straight/build-28.2/ghub/buck.elc is out-of-date
! ~/.config/emacs/.local/straight/build-28.2/ghub/ghub-graphql.elc is out-of-date
! ~/.config/emacs/.local/straight/build-28.2/ghub/ghub-pkg.elc is out-of-date
! ~/.config/emacs/.local/straight/build-28.2/ghub/ghub.elc is out-of-date
! ~/.config/emacs/.local/straight/build-28.2/ghub/glab.elc is out-of-date
! ~/.config/emacs/.local/straight/build-28.2/ghub/gogs.elc is out-of-date
! ~/.config/emacs/.local/straight/build-28.2/ghub/gsexp.elc is out-of-date
! ~/.config/emacs/.local/straight/build-28.2/ghub/gtea.elc is out-of-date
(...)
$ rm -rf ~/.config/emacs/.local/straight/build-28.2/ghub
$ doom sync
(...)
  > Installing packages...
    > Building ghub...
    ✓ Installed 1 packages
(...)
  - Restart Emacs or use 'M-x doom/reload' for changes to take effect