DOCSEARCHbyAlgolia
Submit Docs

Doom Emacs Core

repository·master·Indexed 12 days ago

https://github.com/doomemacs/core

Core components of Doom Emacs, featuring a profile system for managing multiple Emacs configurations and a transactional package manager. Includes documentation for the `doom` CLI, environment variable configuration, system diagnostics via `doom doctor`, and environment management with `doom env`.

Tokens
9K
Snippets
40
Records
53
Agent score
95%

What's inside Doom Emacs

  1. Use the Doom Emacs CLI

    master

    The doom command is the primary interface for managing Doom Emacs. It handles package management, diagnostics, unit tests, and byte-compilation. The CLI can also be used to launch Emacs from different directories or with different private modules using specific flags.

    Common Aliases

    • doom sync (or doom s): Synchronize configuration.
    • doom profile (or doom pf): Manage profiles.
    • doom upgrade (or doom up): Upgrade Doom Emacs.
    • doom doctor (or doom doc): Run diagnostics.
    doom sync

  2. Understand Doom's commit message conventions

    master

    Doom enforces a specific commit message format. When linting fails, it is usually due to one of the following rules:

    Commit Structure

    • Type: Must be one of bump, dev, docs, feat, fix, merge, nit, perf, refactor, release, revert, test, or tweak.
    • Scope: Scopes must be valid (e.g., ci) and must be in lexicographical order if multiple scopes are provided (e.g., feat(scope1,scope2): ...).
    • Summary: The summary follows the type and scope. It should not be needlessly capitalized.
    • Body: Lines in the body should ideally be $\le 50$ characters and must not exceed 72 characters (except for specific long URLs or bump lines).
    • Breaking Changes: If a ! is used in the type (e.g., refactor!:), the body must contain a BREAKING CHANGE: header followed by an explanation.
    • Bump Commits: Commits of type bump must include package reference lines in the body showing the hash diff (e.g., url@hash -> url@hash).

    Trailers

    Valid trailer keys include Fix, Ref, Close, Revert, Amend, Co-authored-by, and Signed-off-by. Each trailer should only contain one value per line and must follow the expected format (e.g., Ref expects a ref, hash, or url).

  3. Migrate from Chemacs to Doom profiles

    master

    To switch from Chemacs to Doom's profile system, follow these steps:

    1. Delete Chemacs from your $EMACSDIR.
    2. Install Doom in $EMACSDIR (e.g., git clone https://github.com/doomemacs/core ~/.config/emacs).
    3. Move your ~/.emacs-profiles.el to ~/.config/doom/profiles.el.
    4. Transform the syntax:
      • Convert string keys to symbols.
      • Adapt env entries to direct key-value pairs.

    Example Transformation:

    Old Chemacs format (~/.emacs-profiles.el):

    (("default"   (user-emacs-directory . "~/.emacs.default/")
             (env ("DOOMDIR" . "~/.doom.private/")))
 ("spacemacs" (user-emacs-directory . "~/spacemacs/")))

    New Doom format (~/.config/emacs/profiles.el):

    ((default   (user-emacs-directory . "~/.emacs.default/")
            ("DOOMDIR" . "~/.doom.private/"))
 (spacemacs (user-emacs-directory . "~/spacemacs/")))
    1. Launch your profile: emacs --profile <name>.
    git clone https://github.com/doomemacs/core ~/.config/emacs

  4. Use doomscript as a shebang for Emacs Lisp scripts

    master

    The doomscript utility allows you to write Emacs Lisp scripts that run with the Doom Emacs framework preloaded. This includes necessary environment variables and the Doom bootstrapper (early-init.el).

    To use it, ensure the bin directory of your Doom installation is in your $PATH, then use #!/usr/bin/env doomscript as the shebang in your script.

    Setup Requirement: To avoid using absolute paths in your shebang lines, add the Doom bin directory to your shell configuration (e.g., .zshrc or .bash_profile):

    export PATH="$HOME/.config/emacs/bin:$PATH"
    #!/usr/bin/env doomscript
(print! "Hello world!")

  5. Synchronize configuration with `doom sync`

    master

    The doom sync command synchronizes your Doom Emacs configuration with the installed packages and environment. It performs tasks equivalent to autoremove, install, autoloads, and recompile.

    You should run this command whenever you:

    1. Modify your doom! block.
    2. Add, remove, or modify package! blocks in your config.
    3. Add, remove, or modify autoloaded functions in module autoloaded files.
    4. Update Doom manually (e.g., via git).
    5. Move your Doom config (either $EMACSDIR or $DOOMDIR) to a new location.
    6. Upgrade or downgrade Emacs (e.g., 29.1 to 29.4).

    Syncing ensures unneeded packages are removed, needed packages are installed, autoloads are up-to-date, and byte-compiled files are not stale.

    doom sync

  6. How to emulate a default fallback profile

    master

    By default, Doom does not have a "default" profile; it simply boots the configuration located in $EMACSDIR. If you want to use a specific profile as your default (to allow it to respect .doomprofile settings), you can register a profile named default in your profiles.el and then set the DOOMPROFILE environment variable or alias the emacs command.

    In your profiles.el:

    ((default
 ...)
)

    In your shell configuration (.zshrc or .bash_profile):

    export DOOMPROFILE=default
# OR
alias emacs='emacs --profile default'
    export DOOMPROFILE=default

  7. Set up and use Doom profiles

    master

    Doom's profile system allows you to switch between multiple Emacs configurations on-demand. For this to work, Doom must be installed in ~/.emacs.d/ or ~/.config/emacs/ (referred to as $EMACSDIR).

    1. Declare your profiles

    You can declare profiles in two ways:

    Explicitly: Create one or multiple profiles.el files in one of these locations:

    • $DOOMDIR/profiles.el (where $DOOMDIR is ~/.doom.d/ or ~/.config/doom/)
    • $EMACSDIR/profiles.el
    • ~/.config/doom-profiles.el
    • ~/.doom-profiles.el

    Implicitly: Create sub-directories in $DOOMDIR/profiles/ or $EMACSDIR/profiles/. Each sub-directory is treated as a profile. You can add a .doomprofile file inside these directories to apply additional settings.

    2. Regenerate the loader

    Whenever you modify your profile declarations, run the following command to regenerate the cached profile loader (located at $EMACSDIR/profiles/init.X.elc):

    doom sync

    3. Launch a profile

    Use the --profile flag with Emacs or the --profile flag with the doom CLI:

    emacs --profile FOO
doom sync --profile FOO
    emacs --profile FOO

  8. Use the Doom Emacs CLI on Windows via PowerShell

    master

    On Windows, the Doom Emacs CLI can be invoked using the bin/doom.ps1 PowerShell script. This script acts as a wrapper that locates your Emacs executable, sets up necessary environment variables, and executes the Doom CLI commands within a batch Emacs process.

    Prerequisites

    • Emacs: Must be installed and available in your PATH, or the path must be specified in the EMACS environment variable.
    • PowerShell: The script searches for pwsh.exe (PowerShell Core) or powershell.exe (Windows PowerShell) to handle secondary execution steps if required.
    # Example: Running a doom command via the PowerShell script
./bin/doom.ps1 sync

  9. Install Doom's git hooks

    master

    To automate development processes and enforce commit message standards, you can install Doom's built-in git hooks (commit-msg and pre-push). This command will create or overwrite the hooks in your .git/hooks directory.

    Note: If you have a non-standard core.hooksPath configured in git, the tool will prompt you before proceeding.

    doom ci deploy-hooks [--force]

  10. Configure Doom CLI environment variables

    master

    You can control the behavior of the doom CLI and the Emacs sessions it spawns using several environment variables:

    VariableDescription
    $EMACSThe Emacs executable to use (defaults to first found in $PATH).
    $EMACSDIRLocation of Doom Emacs installation (defaults to ~/.config/emacs or ~/.emacs.d).
    $DOOMDIRLocation of your private configuration (defaults to ~/.config/doom or ~/.doom.d).
    $DOOMPAGERPager for large output (default: less +g).
    $DOOMPATHColon-delimited list of directories where Doom searches for doom-* executables.
    $DOOMPROFILEThe profile to activate (default: _@0).
    $DOOMPROFILELOADFILEPath to the profile loader script (default: $EMACSDIR/profiles/load.el).
    $DOOMPROFILELOADPATHList of profile config files/directories for implicit profiles.

  11. Configure Emacs and Doom environment variables

    master

    The doom.ps1 script uses several environment variables to determine its behavior and environment. You can override these to customize how the CLI runs:

    VariableDescription
    EMACSThe path to your emacs.exe executable. If not set, the script searches the PATH for emacs.exe
    EMACSDIRThe directory containing your Emacs configuration. If not set, it defaults to the parent directory of the Doom script location
    __DOOMSHInternal variable used to track the shell type (defaults to ps1)
    __DOOMPIDInternal variable used to track the process ID
    __DOOMSTEPInternal variable used for multi-step execution tracking
    __DOOMGEOMThe terminal geometry (columns x lines) used for UI scaling

    Note: Most __DOOM prefixed variables are managed internally by the script to coordinate between Emacs and PowerShell.

  12. Install nerd-icons fonts

    master

    Doom Emacs requires specific fonts for icons. If doom doctor reports that the nerd-icons font is missing, you can install them using one of these methods:

    1. From within Emacs: Run M-x nerd-icons-install-fonts.
    2. Manual Installation: Download and install 'Symbols Nerd Font' from https://nerdfonts.com/ or via your OS package manager. If you use a non-standard font, you may need to update the nerd-icons-font-names or nerd-icons-font-family variables in your config.