mirror of
https://github.com/nix-community/nix-doom-emacs
synced 2025-08-03 12:27:27 -05:00
Merge pull request #266 from ribosomerocker/doc-branch
Documentation overhaul
This commit is contained in:
Thiago Kenji Okada
GitHub
132
README.md
132
README.md
@ -1,3 +1,7 @@
|
|||||||
|
| index | | |
|
||||||
|
| --- | --- | --- |
|
||||||
|
|**readme**|[reference](./docs/reference.md)|[faq](./docs/faq.md)|
|
||||||
|
|
||||||
# nix-doom-emacs
|
# nix-doom-emacs
|
||||||
|
|
||||||
| | Status |
|
| | Status |
|
||||||
@ -6,8 +10,7 @@
|
|||||||
| Dependency updater | [](https://github.com/nix-community/nix-doom-emacs/actions/workflows/update-dependencies.yml?query=branch%3Amaster) |
|
| Dependency updater | [](https://github.com/nix-community/nix-doom-emacs/actions/workflows/update-dependencies.yml?query=branch%3Amaster) |
|
||||||
| Matrix Chat | [](https://matrix.to/#/#doom-emacs:nixos.org) |
|
| Matrix Chat | [](https://matrix.to/#/#doom-emacs:nixos.org) |
|
||||||
|
|
||||||
Nix expression to install and configure
|
nix-doom-emacs (abbreviated as NDE) provides a customisable Nix derivation for [Doom Emacs](https://github.com/doomemacs/doomemacs).
|
||||||
[doom-emacs](https://github.com/doomemacs/doomemacs).
|
|
||||||
|
|
||||||
The expression builds a `doom-emacs` distribution with dependencies
|
The expression builds a `doom-emacs` distribution with dependencies
|
||||||
pre-installed based on an existing `~/.doom.d` directory.
|
pre-installed based on an existing `~/.doom.d` directory.
|
||||||
@ -17,121 +20,20 @@ some may not be fully compatible as the version available in NixOS or
|
|||||||
[emacs-overlay](https://github.com/nix-community/emacs-overlay) may not be
|
[emacs-overlay](https://github.com/nix-community/emacs-overlay) may not be
|
||||||
compatible with the `doom-emacs` requirements.
|
compatible with the `doom-emacs` requirements.
|
||||||
|
|
||||||
## Getting started
|
# Quick Start
|
||||||
|
|
||||||
Using [home-manager](https://github.com/nix-community/home-manager):
|
If you want to get a taste of nix-doom-emacs, you can run ``nix run github:nix-community/nix-doom-emacs``
|
||||||
|
Which will run nix-doom-emacs with an example configuration.
|
||||||
|
|
||||||
``` nix
|
Pick which setup you're using here (if you're not using NixOS or Home-Manager, then you should use standalone):
|
||||||
{ pkgs, ... }:
|
|
||||||
|
|
||||||
let
|
| Home-Manager | NixOS | Standalone |
|
||||||
doom-emacs = pkgs.callPackage (builtins.fetchTarball {
|
| --- | --- | --- |
|
||||||
url = https://github.com/nix-community/nix-doom-emacs/archive/master.tar.gz;
|
| [Flake + Home-Manager](./docs/reference.md#home-manager) | [NixOS](./docs/reference.md#nixos) | [Standalone](./docs/reference.md#standalone) |
|
||||||
}) {
|
|
||||||
doomPrivateDir = ./doom.d; # Directory containing your config.el init.el
|
|
||||||
# and packages.el files
|
|
||||||
};
|
|
||||||
in {
|
|
||||||
home.packages = [ doom-emacs ];
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
`./doom.d` should contain the following three files: `config.el`, `init.el` and
|
# Hacking
|
||||||
`packages.el`. If you don't already have an existing `doom-emacs` configuration,
|
|
||||||
you can use the contents of `test/doom.d` as a template.
|
|
||||||
|
|
||||||
Using `flake.nix`:
|
This project is under MIT license. Our [issue tracker](https://github.com/nix-community/nix-doom-emacs/issues) has some open issues,
|
||||||
|
the `PR wanted` label is for issues that need PRs to fix them.
|
||||||
``` nix
|
Also, talk to us in the [Matrix Chat](https://matrix.to/#/#doom-emacs:nixos.org) to discuss ideas for future improvements.
|
||||||
{
|
Contributions are welcome.
|
||||||
inputs = {
|
|
||||||
home-manager.url = "github:nix-community/home-manager";
|
|
||||||
nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
|
|
||||||
};
|
|
||||||
|
|
||||||
outputs = {
|
|
||||||
self,
|
|
||||||
nixpkgs,
|
|
||||||
lib,
|
|
||||||
home-manager,
|
|
||||||
nix-doom-emacs,
|
|
||||||
...
|
|
||||||
}: {
|
|
||||||
nixosConfigurations.exampleHost = lib.nixosSystem {
|
|
||||||
system = "x86_64-linux";
|
|
||||||
modules = [
|
|
||||||
home-manager.nixosModules.home-manager
|
|
||||||
({
|
|
||||||
home-manager.users.exampleUser = lib.mkMerge [
|
|
||||||
nix-doom-emacs.hmModule
|
|
||||||
{ ... }: {
|
|
||||||
programs.doom-emacs = {
|
|
||||||
enable = true;
|
|
||||||
doomPrivateDir = ./doom.d;
|
|
||||||
};
|
|
||||||
}
|
|
||||||
];
|
|
||||||
})
|
|
||||||
];
|
|
||||||
};
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Under the hood
|
|
||||||
|
|
||||||
This expression leverages
|
|
||||||
[nix-straight.el](https://github.com/nix-community/nix-straight.el) under the hood for
|
|
||||||
installing dependencies. The restrictions of that package apply here too.
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
instead of running emacs.d/bin/doom, once you have update your config files (packages.el, init.el, config.el), rebuild doom-emacs with nix. If you are using home-manager, simply run `home-manager switch`
|
|
||||||
|
|
||||||
## Troubleshooting
|
|
||||||
|
|
||||||
On macOS on a fresh install, you might run into the error `Too many files open`. running `ulimit -S -n 2048` will only work for the duration of your shell and will fix the error
|
|
||||||
|
|
||||||
## Installing emacs packages
|
|
||||||
|
|
||||||
In the initial packages.el instructions for how to install packages can be
|
|
||||||
found. However some packages might require a particular software dependency to
|
|
||||||
be installed. Trying to install those would give you an error of the type:
|
|
||||||
`Searching for program: No such file or directory, git` (Missing git dependency)
|
|
||||||
Here is how you would go installing
|
|
||||||
[magit-delta](https://github.com/dandavison/magit-delta) for example (which
|
|
||||||
requires git).
|
|
||||||
|
|
||||||
Under the line:
|
|
||||||
`doomPrivateDir = ./doom.d;`
|
|
||||||
in your configuration, you would add the following:
|
|
||||||
|
|
||||||
```Nix
|
|
||||||
{
|
|
||||||
emacsPackagesOverlay = self: super: {
|
|
||||||
magit-delta = super.magit-delta.overrideAttrs (esuper: {
|
|
||||||
buildInputs = esuper.buildInputs ++ [ pkgs.git ];
|
|
||||||
});
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
To make the git dependency available. trying to rebuild doom-emacs with
|
|
||||||
`home-manager switch` should work correctly now.
|
|
||||||
|
|
||||||
## Using the daemon
|
|
||||||
|
|
||||||
To use the daemon, simply enable the emacs service (with `NixOS`, `home-manager`
|
|
||||||
or `nix-darwin`) and use the doom emacs package. `doom-emacs` will need to be
|
|
||||||
referenced at the top of your config file.
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{
|
|
||||||
services.emacs = {
|
|
||||||
enable = true;
|
|
||||||
package = doom-emacs; # Not needed if you're using the Home-Manager module instead
|
|
||||||
};
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
to connect to the daemon you can now run `emacsclient -c`
|
|
||||||
|
|||||||
61
docs/faq.md
Normal file
61
docs/faq.md
Normal file
@ -0,0 +1,61 @@
|
|||||||
|
| index | | |
|
||||||
|
| --- | --- | --- |
|
||||||
|
|[readme](../README.md)|[reference](./docs/reference.md)|**faq**|
|
||||||
|
|
||||||
|
# Frequently Asked Questions
|
||||||
|
|
||||||
|
## I am new to Nix. Is this the only way to use Doom Emacs with Nix/NixOS?
|
||||||
|
|
||||||
|
Nope! Doom Emacs is still perfectly usable imperatively. In fact, the very author of Doom Emacs uses NixOS and install Doom Emacs with an ["imperative" setup](https://github.com/hlissner/dotfiles/blob/master/modules/editors/emacs.nix). You can follow the instructions on the [Doom Emacs GitHub repository](https://github.com/doomemacs/doomemacs) to get a working setup.
|
||||||
|
|
||||||
|
|
||||||
|
## How do I add a non-(M)ELPA dependency to a package's build?
|
||||||
|
|
||||||
|
You'd usually need to do this when a (M)ELPA pakage needs some package to exist on your system, like `git` for example.
|
||||||
|
|
||||||
|
You should use the `emacsPackagesOverlay` attribute. Here's an example that installs `magit-delta`, which depends on Git:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
programs.doom-emacs = {
|
||||||
|
# ...
|
||||||
|
emacsPackagesOverlay = self: super: {
|
||||||
|
magit-delta = super.magit-delta.overrideAttrs (esuper: {
|
||||||
|
buildInputs = esuper.buildInputs ++ [ pkgs.git ];
|
||||||
|
});
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## How do I add a package that's only on GitHub (or any Git frontend)
|
||||||
|
|
||||||
|
If you try to add a package that isn't from (M)ELPA, you'd get this error: `Package not available`. This is because `nix-straight.el` assumes that packages are on emacs-overlay's packages, which only include (M)ELPA.
|
||||||
|
This question assumes the package uses GitHub, so it uses the `fetchFromGitHub` function. To see which function you'd need to use, you should look at [the Nixpkgs manual's fetchers section](https://nixos.org/manual/nixpkgs/stable/#chap-pkgs-fetchers)
|
||||||
|
For an example, this installs `idris2-mode` which isn't on (M)ELPA, but is hosted on GitHub:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
programs.doom-emacs = {
|
||||||
|
# ...
|
||||||
|
emacsPackagesOverlay = self: super: {
|
||||||
|
idris2-mode = self.trivialBuild {
|
||||||
|
pname = "idris2-mode";
|
||||||
|
ename = "idris2-mode";
|
||||||
|
version = "unstable-2022-09-21";
|
||||||
|
buildInputs = [ self.prop-menu ];
|
||||||
|
src = pkgs.fetchFromGitHub {
|
||||||
|
owner = "idris-community";
|
||||||
|
repo = "idris2-mode";
|
||||||
|
rev = "4a3f9cdb1a155da59824e39f0ac78ccf72f2ca97";
|
||||||
|
sha256 = "sha256-TxsGaG2fBRWWP9aas59kiNnUVD4ZdNlwwaFbM4+n81c=";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## nix-doom-emacs isn't working if I set DOOMDIR or EMACSDIR
|
||||||
|
|
||||||
|
You shouldn't do that. nix-doom-emacs' home-manager module writes `~/.emacs.d` in your `$HOME`. Make sure to remove the environment variables from your configuration, then reboot after rebuilding it. If for just the session, you can just `unset` those 2 variables.
|
||||||
|
|
||||||
|
## It errors with "Too many files open"!
|
||||||
|
|
||||||
|
Running `ulimit -S -n 2048` will fix it for the duration of your shell session.
|
||||||
242
docs/reference.md
Normal file
242
docs/reference.md
Normal file
@ -0,0 +1,242 @@
|
|||||||
|
| index | | |
|
||||||
|
| --- | --- | --- |
|
||||||
|
|[readme](../README.md)|**reference**|[faq](./docs/faq.md)|
|
||||||
|
|
||||||
|
# nix-doom-emacs reference
|
||||||
|
|
||||||
|
nix-doom-emacs uses [`nix-straight.el`](https://github.com/nix-community/nix-straight.el) under the hood to install dependencies. It's a low level wrapper to integrate Nix with [`straight.el`](https://github.com/radian-software/straight.el). It is maintained by the same people as this project.
|
||||||
|
|
||||||
|
Currently, `nix-straight.el` only extracts package names and uses [`emacs-overlay`](https://github.com/nix-community/emacs-overlay) to obtain the package sources. This works most of the time but occasionally results in obscure issues with recently updated packages.
|
||||||
|
|
||||||
|
# Getting Started
|
||||||
|
|
||||||
|
In all of these methods, you'll need your Doom Emacs configuration. It should contain the following three files:
|
||||||
|
`config.el`, `init.el` and `packages.el`. If you don't already have an existing `doom-emacs` configuration, you can use the contents of `test/doom.d` as a template.
|
||||||
|
|
||||||
|
## Home-Manager
|
||||||
|
|
||||||
|
### With Flakes
|
||||||
|
|
||||||
|
`File: flake.nix`
|
||||||
|
```nix
|
||||||
|
{
|
||||||
|
inputs = {
|
||||||
|
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||||
|
home-manager.url = "github:nix-community/home-manager";
|
||||||
|
nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
|
||||||
|
};
|
||||||
|
|
||||||
|
outputs = {
|
||||||
|
self,
|
||||||
|
nixpkgs,
|
||||||
|
home-manager,
|
||||||
|
nix-doom-emacs,
|
||||||
|
...
|
||||||
|
}: {
|
||||||
|
nixosConfigurations.exampleHost = nixpkgs.lib.nixosSystem {
|
||||||
|
system = "x86_64-linux";
|
||||||
|
modules = [
|
||||||
|
home-manager.nixosModules.home-manager
|
||||||
|
{
|
||||||
|
home-manager.users.exampleUser = { ... }: {
|
||||||
|
imports = [ nix-doom-emacs.hmModule ];
|
||||||
|
programs.doom-emacs = {
|
||||||
|
enable = true;
|
||||||
|
doomPrivateDir = ./doom.d; # Directory containing your config.el, init.el
|
||||||
|
# and packages.el files
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
];
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Without Flakes
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{ pkgs, ... }:
|
||||||
|
|
||||||
|
let
|
||||||
|
doom-emacs = pkgs.callPackage (builtins.fetchTarball {
|
||||||
|
url = https://github.com/nix-community/nix-doom-emacs/archive/master.tar.gz;
|
||||||
|
}) {
|
||||||
|
doomPrivateDir = ./doom.d; # Directory containing your config.el, init.el
|
||||||
|
# and packages.el files
|
||||||
|
};
|
||||||
|
in {
|
||||||
|
home.packages = [ doom-emacs ];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
## NixOS
|
||||||
|
|
||||||
|
`File: flake.nix`
|
||||||
|
```nix
|
||||||
|
{
|
||||||
|
inputs = {
|
||||||
|
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||||||
|
nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
|
||||||
|
};
|
||||||
|
|
||||||
|
outputs = {
|
||||||
|
self,
|
||||||
|
nixpkgs,
|
||||||
|
nix-doom-emacs,
|
||||||
|
...
|
||||||
|
}: {
|
||||||
|
nixosConfigurations.exampleHost = nixpkgs.lib.nixosSystem rec {
|
||||||
|
system = "x86_64-linux";
|
||||||
|
modules = [
|
||||||
|
{
|
||||||
|
environment.systemPackages =
|
||||||
|
let
|
||||||
|
doom-emacs = nix-doom-emacs.packages.${system}.default.override {
|
||||||
|
doomPrivateDir = ./doom.d;
|
||||||
|
};
|
||||||
|
in [
|
||||||
|
doom-emacs
|
||||||
|
];
|
||||||
|
}
|
||||||
|
# ...
|
||||||
|
];
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
You can see all overridable parameters of nix-doom-emacs in [default.nix](../default.nix).
|
||||||
|
|
||||||
|
## Standalone
|
||||||
|
|
||||||
|
### Flake
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{
|
||||||
|
description = "nix-doom-emacs shell";
|
||||||
|
|
||||||
|
inputs = {
|
||||||
|
nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
|
||||||
|
nix-doom-emacs.url = "github:nix-community/nix-doom-emacs";
|
||||||
|
};
|
||||||
|
|
||||||
|
outputs = { self, nixpkgs, nix-doom-emacs, ... }:
|
||||||
|
let
|
||||||
|
system = "x86_64-linux";
|
||||||
|
pkgs = import nixpkgs { inherit system; };
|
||||||
|
doom-emacs = nix-doom-emacs.packages.${system}.default.override {
|
||||||
|
doomPrivateDir = ./doom.d;
|
||||||
|
};
|
||||||
|
in
|
||||||
|
{
|
||||||
|
devShells.${system}.default = pkgs.mkShell {
|
||||||
|
buildInputs = [ doom-emacs ];
|
||||||
|
};
|
||||||
|
};
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Non-Flake
|
||||||
|
```nix
|
||||||
|
{ pkgs ? import <nixpkgs> { } }:
|
||||||
|
|
||||||
|
let
|
||||||
|
repo = pkgs.fetchFromGitHub {
|
||||||
|
owner = "nix-community";
|
||||||
|
repo = "nix-doom-emacs";
|
||||||
|
rev = "<commit>";
|
||||||
|
sha256 = "<hash>";
|
||||||
|
};
|
||||||
|
nix-doom-emacs = pkgs.callPackage (import repo) {
|
||||||
|
doomPrivateDir = ./doom.d;
|
||||||
|
};
|
||||||
|
in
|
||||||
|
pkgs.mkShell {
|
||||||
|
buildInputs = [ nix-doom-emacs ];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
# Setup
|
||||||
|
|
||||||
|
## Emacs daemon
|
||||||
|
|
||||||
|
If you use the Home-Manager module, you can enable it via `services.emacs.enable = true;`. The Home-Manager module will do the rest for you.
|
||||||
|
|
||||||
|
If you're not, and you're using a standalone method (NixOS/nix-darwin without Home-Manager) instead, you'll need:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.emacs = {
|
||||||
|
enable = true;
|
||||||
|
package = inputs.doom-emacs.packages.${system}.doom-emacs.override {
|
||||||
|
doomPrivateDir = ./doom.d;
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
You can now run `emacsclient -c` to connect to the daemon.
|
||||||
|
|
||||||
|
## Custom Emacs derivations (i.e., PGTK, NativeComp)
|
||||||
|
|
||||||
|
If you're using the Home-Manager module, you can use the `emacsPackage` attribute after applying `emacs-overlay` to your nixpkgs:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
programs.doom-emacs = {
|
||||||
|
enable = true;
|
||||||
|
doomPrivateDir = ./doom.d;
|
||||||
|
emacsPackage = pkgs.emacsPgtk;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
For standalone usage with Flakes:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
let
|
||||||
|
# ...
|
||||||
|
doom-emacs = nix-doom-emacs.packages.${system}.default.override {
|
||||||
|
doomPrivateDir = ./doom.d;
|
||||||
|
emacsPackage = pkgs.emacsPgtkNativeComp;
|
||||||
|
};
|
||||||
|
in {
|
||||||
|
# ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
And for non-Flakes usage:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
let
|
||||||
|
# ...
|
||||||
|
nix-doom-emacs = pkgs.callPackage (import repo) {
|
||||||
|
doomPrivateDir = ./doom.d;
|
||||||
|
emacsPackage = pkgs.emacsPgtkNativeComp
|
||||||
|
};
|
||||||
|
in {
|
||||||
|
# ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Updating configuration
|
||||||
|
|
||||||
|
Note that, unlike imperative `Doom Emacs`, we do not have a `doom sync`. Our project builds an Emacs with your Doom configuration embedded in it. `doom sync` just updates packages.
|
||||||
|
This doesn't mean that you can't update your packages and configuration, obviously:
|
||||||
|
|
||||||
|
To update your Doom Emacs config, you simply rebuild your configuration. For example, in NixOS you can use `nixos-rebuild switch` (or `home-manager switch` if you use Home-Manager standalone). nix-doom-emacs will do everything else for you.
|
||||||
|
|
||||||
|
In an imperative environment, Doom updates can break Emacs with no easy way to roll back.
|
||||||
|
nix-doom-emacs moves the moving parts of your Emacs installation into the Nix build sandbox.
|
||||||
|
|
||||||
|
## Building third-party Emacs packages
|
||||||
|
|
||||||
|
Though beyond the scope of this document, [`trivialBuild`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/emacs/trivial.nix) is a nixpkgs function to trivially build Emacs packages. You can use it to build e.g. local packages or packages hosted on Git repositories. There is also a family of functions in nixpkgs which are made to build Emacs packages, such as:
|
||||||
|
|
||||||
|
- [`generic`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/emacs/generic.nix): This is the "base" function which all the other build functions are derived from
|
||||||
|
- [`elpaBuild`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/emacs/elpa.nix): For ELPA packages
|
||||||
|
- [`melpaBuild`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/emacs/elpa.nix): For MELPA packages
|
||||||
|
|
||||||
|
To find examples of how they're used, try to [search nixpkgs](https://github.com/NixOS/nixpkgs/search) for usages of them.
|
||||||
|
|
||||||
|
# Support
|
||||||
|
|
||||||
|
If you encounter any issues while using nix-doom-emacs, you can find some of us in the [Matrix room](https://matrix.to/#/#doom-emacs:nixos.org).
|
||||||
Reference in New Issue
Block a user