91 lines
3.7 KiB
Markdown
91 lines
3.7 KiB
Markdown
# Emacs + Nix Setup: Overview and Package Guide
|
|
|
|
## Introduction
|
|
|
|
This document explains the Emacs ecosystem and the Nix-based configuration used in this project. It covers the purpose of key Emacs packages, how they are managed with Nix, and how to extend or troubleshoot your setup.
|
|
|
|
---
|
|
|
|
## Why Use Nix for Emacs?
|
|
|
|
- **Reproducibility:** Nix ensures your Emacs environment is consistent across machines and rebuilds.
|
|
- **Declarative Configuration:** All packages and dependencies are listed in a single place (`emacs.nix`), making it easy to update or share.
|
|
- **Isolation:** Nix prevents conflicts between Emacs packages and system/global packages.
|
|
|
|
---
|
|
|
|
## Emacs Packages in This Setup
|
|
|
|
### Navigation & Completion
|
|
|
|
- **vertico, consult, marginalia, orderless, embark, embark-consult, corfu, cape:** Modern completion and minibuffer enhancements for fast, fuzzy, and context-aware navigation.
|
|
- **projectile:** Project management and navigation.
|
|
|
|
### Version Control
|
|
|
|
- **magit:** The best Git interface for Emacs.
|
|
- **forge:** GitHub/GitLab/Magit integration for issues and pull requests.
|
|
|
|
### Development Tools
|
|
|
|
- **lsp-mode, lsp-ui:** Language Server Protocol support for IDE-like features.
|
|
- **company:** In-buffer code completion.
|
|
- **flycheck:** On-the-fly syntax checking.
|
|
- **yasnippet:** Snippet expansion for faster coding.
|
|
- **elisp-slime-nav:** Easy navigation of Emacs Lisp code.
|
|
- **aggressive-indent:** Keeps your code automatically indented.
|
|
- **highlight-defined:** Highlights defined symbols in Emacs Lisp.
|
|
|
|
### Language Support
|
|
|
|
- **nix-mode:** Nix language editing.
|
|
- **rust-mode, python-mode, typescript-mode, json-mode, yaml-mode, markdown-mode:** Major modes for popular languages and formats.
|
|
- **elisp-ls:** Emacs Lisp Language Server for LSP features in Emacs Lisp.
|
|
|
|
### Org & Knowledge Management
|
|
|
|
- **org, org-roam, org-roam-ui:** Org-mode for notes, tasks, and literate programming; org-roam for Zettelkasten-style knowledge management.
|
|
|
|
### UI & Usability
|
|
|
|
- **doom-themes, doom-modeline, all-the-icons, rainbow-delimiters, highlight-indent-guides:** Visual enhancements for a modern, readable Emacs.
|
|
- **smartparens, expand-region, multiple-cursors, avy, ace-window:** Editing and navigation power tools.
|
|
- **vterm:** Terminal emulator inside Emacs.
|
|
|
|
---
|
|
|
|
## How the Nix Setup Works
|
|
|
|
- The file `modules/development/emacs.nix` defines a function that builds a custom Emacs with all the above packages.
|
|
- Packages are grouped by purpose (essential, minimal, development, workstation) and selected based on your machine profile.
|
|
- When you rebuild your system or run `nix develop`, Nix fetches and builds all required Emacs packages.
|
|
- Environment variables (like `AG_PATH`, `FD_PATH`, etc.) are set for Emacs to use external tools.
|
|
|
|
---
|
|
|
|
## Extending Your Setup
|
|
|
|
- To add a new package, add it to the appropriate list in `emacs.nix` (e.g., under `development = epkgs: with epkgs; [ ... ]`).
|
|
- Rebuild your system or development shell to apply changes.
|
|
- For packages not in Nixpkgs, consider using MELPA as a fallback, but prefer Nix for reproducibility.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
- If you see `Cannot open load file` errors, make sure the package is included in your Nix config.
|
|
- For missing language servers, check if the correct Nix package is used (e.g., `elisp-ls` for Emacs Lisp LSP).
|
|
- Use `emacs --daemon --debug-init` to debug startup issues.
|
|
|
|
---
|
|
|
|
## Resources
|
|
|
|
- [NixOS Emacs Wiki](https://nixos.wiki/wiki/Emacs)
|
|
- [Emacs Manual](https://www.gnu.org/software/emacs/manual/)
|
|
- [Nixpkgs Emacs Packages](https://search.nixos.org/packages?channel=unstable&show=emacsPackages)
|
|
- [System Crafters: Emacs from Scratch](https://systemcrafters.net/)
|
|
|
|
---
|
|
|
|
This setup gives you a modern, reproducible, and powerful Emacs environment managed entirely by Nix. Happy hacking!
|