mirror of
https://github.com/nix-community/nix-doom-emacs
synced 2025-08-03 12:27:27 -05:00
Documentation overhaul
This commit is contained in:
Mon Aaraj
120
README.md
120
README.md
@ -17,121 +17,5 @@ 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
|
||||
compatible with the `doom-emacs` requirements.
|
||||
|
||||
## Getting started
|
||||
|
||||
Using [home-manager](https://github.com/nix-community/home-manager):
|
||||
|
||||
``` 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 ];
|
||||
}
|
||||
```
|
||||
|
||||
`./doom.d` 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.
|
||||
|
||||
Using `flake.nix`:
|
||||
|
||||
``` nix
|
||||
{
|
||||
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`
|
||||
# Documentation
|
||||
To know how to use Nix-Doom-Emacs, and to fix other issues, check the [documentation](./docs)
|
||||
|
||||
139
docs/README.md
Normal file
139
docs/README.md
Normal file
@ -0,0 +1,139 @@
|
||||
# Documentation for Nix-Doom-Emacs
|
||||
|
||||
Nix-Doom-Emacs (also commonly referred to as NDE in chatrooms) is a project with a lot of moving pieces and hacks; it's a project that is itself a fork of another project that has these moving pieces. Thus, it's not out of the blue to expect it to be a tiny bit more buggy for most people than other software. If you encounter any issues that make it not usable to you (or if you need support), please talk to us first in the [Matrix room](https://matrix.to/#/#doom-emacs:nixos.org) and if it's indeed a bug of Nix-Doom-Emacs, file it in the [issue tracker](https://github.com/nix-community/nix-doom-emacs/issues). If you find this documentation unclear or incomplete, please let us know as well.
|
||||
|
||||
Here's the [FAQ](./faq.md)
|
||||
|
||||
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 add Nix integration over straight.el, the declarative package manager used by Doom Emacs.
|
||||
|
||||
If you're not aware yet, then:
|
||||
|
||||
#### **WARNING**: HERE BE DRAGONS! THIS IS A FRAGILE PROJECT
|
||||
|
||||
# Getting Started
|
||||
|
||||
To get started, we suggest these methods. They are ordered from most suggested to least suggested.
|
||||
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.
|
||||
|
||||
The Doom configuration will be referred to as `./doom.d` in these snippets. You can name it whatever you like.
|
||||
|
||||
## Flake + Home-Manager
|
||||
|
||||
`File: flake.nix`
|
||||
```nix
|
||||
{
|
||||
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,
|
||||
...
|
||||
}:
|
||||
let
|
||||
system = "x86_64-linux";
|
||||
specialArgs = { inherit inputs; };
|
||||
in {
|
||||
nixosConfigurations.exampleHost = lib.nixosSystem {
|
||||
inherit system specialArgs;
|
||||
modules = [
|
||||
./default.nix
|
||||
home-manager.nixosModules.home-manager
|
||||
{
|
||||
home-manager.users.exampleUser.imports = [ ./home.nix ];
|
||||
}
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
`File: home.nix`
|
||||
```nix
|
||||
{ config, pkgs, inputs, ... }: {
|
||||
imports = [ inputs.nix-doom-emacs.hmModule ];
|
||||
|
||||
# ...
|
||||
programs.doom-emacs = {
|
||||
enable = true;
|
||||
doomPrivateDir = ./doom.d; # Directory containing your config.el, init.el
|
||||
# and packages.el files
|
||||
};
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
## Non-Flake Home-Manager
|
||||
|
||||
```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 ];
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Standalone
|
||||
|
||||
Using Nix-Doom-Emacs standalone isn't recommended, especially if you're a beginner.
|
||||
|
||||
`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,
|
||||
lib,
|
||||
nix-doom-emacs,
|
||||
...
|
||||
}:
|
||||
let
|
||||
system = "x86_64-linux";
|
||||
specialArgs = { inherit inputs; };
|
||||
in {
|
||||
nixosConfigurations.exampleHost = lib.nixosSystem {
|
||||
inherit system specialArgs;
|
||||
modules = [
|
||||
./default.nix
|
||||
# ...
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
`File: default.nix`
|
||||
```nix
|
||||
{ config, nixpkgs, lib, inputs }: {
|
||||
# ...
|
||||
environment.systemPackages =
|
||||
let
|
||||
doom-emacs = inputs.nix-doom-emacs.packages.${system}.default.override {
|
||||
doomPrivateDir = ./doom;
|
||||
};
|
||||
in [
|
||||
doom-emacs
|
||||
];
|
||||
# ...
|
||||
}
|
||||
```
|
||||
122
docs/faq.md
Normal file
122
docs/faq.md
Normal file
@ -0,0 +1,122 @@
|
||||
# FAQ
|
||||
This is more meant as a "Fully Anticipated Questions" than a "Frequently Asked Questions", as they're anticipated as common pitfalls to using NDE.
|
||||
|
||||
## OK, I put your snippets into my NixOS configuration, and I put my Doom Emacs configuration as well. How do I `doom sync`?
|
||||
|
||||
To update your Doom Emacs config, you simply run `nixos-rebuild switch` (or `home-manager switch` if you use Home-Manager standalone). Nix-Doom-Emacs will do everything else for you.
|
||||
|
||||
## How do I install my favourite package?
|
||||
|
||||
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 ];
|
||||
});
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### But what if my package is from a Git source, and isn't on ELPA?
|
||||
|
||||
This requires a few more lines, but it isn't by any means difficult. For an example, this installs `idris2-mode` which isn't on ELPA, but is hosted on GitHub:
|
||||
|
||||
```nix
|
||||
programs.doom-emacs = {
|
||||
# ...
|
||||
emacsPackagesOverlay = self: super: {
|
||||
idris2-mode = self.trivialBuild {
|
||||
pname = "idris2-mode";
|
||||
ename = "idris2-mode";
|
||||
version = "0.0.0";
|
||||
buildInputs = [ self.prop-menu ];
|
||||
src = pkgs.fetchFromGitHub {
|
||||
owner = "idris-community";
|
||||
repo = "idris2-mode";
|
||||
rev = "4a3f9cdb1a155da59824e39f0ac78ccf72f2ca97";
|
||||
sha256 = "sha256-TxsGaG2fBRWWP9aas59kiNnUVD4ZdNlwwaFbM4+n81c=";
|
||||
};
|
||||
};
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Help! My favourite package doesn't work after adding it in!
|
||||
|
||||
This usually happens when the package depends on either some ELPA package or a normal package that you need to add into the `buildInputs` to make it work.
|
||||
Let's take the above `idris2-mode` package, and I'll remove the `buildInputs` line:
|
||||
|
||||
**WARNING**: THIS IS ERRONEOUS CODE FOR DEMONSTRATION. DO NOT USE THIS SNIPPET, THE ABOVE ONE IS THE FUNCTIONING VERSION.
|
||||
```nix
|
||||
programs.doom-emacs = {
|
||||
# ...
|
||||
emacsPackagesOverlay = self: super: {
|
||||
idris2-mode = self.trivialBuild {
|
||||
pname = "idris2-mode";
|
||||
ename = "idris2-mode";
|
||||
version = "0.0.0";
|
||||
src = pkgs.fetchFromGitHub {
|
||||
owner = "idris-community";
|
||||
repo = "idris2-mode";
|
||||
rev = "4a3f9cdb1a155da59824e39f0ac78ccf72f2ca97";
|
||||
sha256 = "sha256-TxsGaG2fBRWWP9aas59kiNnUVD4ZdNlwwaFbM4+n81c=";
|
||||
};
|
||||
};
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
This will error with (this is a part of the build log):
|
||||
|
||||
```
|
||||
In toplevel form:
|
||||
idris2-hole-list.el:27:2: Error: Cannot open load file: No such file or directory, prop-menu
|
||||
|
||||
In toplevel form:
|
||||
idris2-info.el:29:2: Error: Cannot open load file: No such file or directory, prop-menu
|
||||
|
||||
In idris2-ipkg-pkgs-flags-for-current-buffer:
|
||||
idris2-ipkg-mode.el:372:2: Warning: docstring wider than 80 characters
|
||||
|
||||
In toplevel form:
|
||||
idris2-mode.el:20:2: Error: Cannot open load file: No such file or directory, prop-menu
|
||||
|
||||
In idris2-prover-end:
|
||||
idris2-prover.el:378:2: Warning: docstring wider than 80 characters
|
||||
|
||||
In toplevel form:
|
||||
idris2-repl.el:29:2: Error: Cannot open load file: No such file or directory, prop-menu
|
||||
```
|
||||
|
||||
The way to fix it is by just adding the dependency it's complaining about.
|
||||
|
||||
## How do I enable the service?
|
||||
|
||||
There aren't many complications about this. If you use the Home-Manager module, it's simply `services.emacs.enable = true;`. The Home-Manager module will do the rest for you.
|
||||
|
||||
But if you're not, and you're using a standalone method, you'll need:
|
||||
|
||||
```nix
|
||||
services.emacs = {
|
||||
enable = true;
|
||||
package = inputs.doom-emacs.packages.${system}.doom-emacs;
|
||||
};
|
||||
```
|
||||
|
||||
You can now run `emacsclient -c` to connect to the daemon.
|
||||
|
||||
## What is `trivialBuild`?
|
||||
|
||||
Though beyond the scope of this document, `trivialBuild` 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. It is not a Nix-Doom-Emacs tool.
|
||||
|
||||
## Help! Nix-Doom-Emacs isn't working if I set DOOMDIR or EMACSDIR
|
||||
|
||||
You shouldn't do that. The only thing that Nix-Doom-Emacs writes in your $HOME is `~/.emacs.d/init.el`, which points to the Nix store. Make sure to remove them from your configuration, then reboot after rebuilding it. If for just the session, you can just `unset` those 2 variables.
|
||||
|
||||
# Help! on MacOS, it says "Too many files open"!
|
||||
|
||||
Running `ulimit -S -n 2048` will fix it for the duration of your shell session.
|
||||
|
||||
Reference in New Issue
Block a user