awesome-emacs/nix-doom-emacs
1
0
Fork 0
mirror of https://github.com/nix-community/nix-doom-emacs synced 2025-08-21 13:53:39 -05:00
Code Issues Packages Projects Releases Wiki Activity

resolve reviews

Browse Source
This commit is contained in:
Mon Aaraj
2022-09-21 20:08:03 +03:00
parent 1a524776a4
commit 5952ea8b87
3 changed files with 37 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
README.md
View File

@@ -1,6 +1,4 @@
| readme | reference | faq | | readme | [reference](./docs/reference.md)| [faq](./docs/faq.md) |
| --- | --- | --- |
| this document | [docs/reference.md](./docs/reference.md)| [docs/faq.md](./docs/faq.md) |
# nix-doom-emacs # nix-doom-emacs
@@ -10,10 +8,8 @@
| Dependency updater | [![Dependency Updater Status](https://github.com/nix-community/nix-doom-emacs/workflows/Update%20Dependencies/badge.svg?branch=master)](https://github.com/nix-community/nix-doom-emacs/actions/workflows/update-dependencies.yml?query=branch%3Amaster) | | Dependency updater | [![Dependency Updater Status](https://github.com/nix-community/nix-doom-emacs/workflows/Update%20Dependencies/badge.svg?branch=master)](https://github.com/nix-community/nix-doom-emacs/actions/workflows/update-dependencies.yml?query=branch%3Amaster) |
| Matrix Chat | [![Matrix Chat](https://img.shields.io/static/v1?label=chat&message=doom-emacs&color=brightgreen&logo=matrix)](https://matrix.to/#/#doom-emacs:nixos.org) | | Matrix Chat | [![Matrix Chat](https://img.shields.io/static/v1?label=chat&message=doom-emacs&color=brightgreen&logo=matrix)](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 project has lots of moving pieces and hacks. Users are expected to know their way around using (and especially debugging) Nix and Emacs Lisp in order to use this project.
nix-doom-emacs (also commonly referred to as NDE in chatrooms) is a project with lots of moving pieces and hacks. Users are expected to know their way around using (and especially debugging) Nix and Emacs Lisp in order to use this project.
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.
@@ -33,3 +29,10 @@ Pick which setup you're using here (if you're not using NixOS or Home-Manager, t
| Home-Manager | NixOS | Standalone | | Home-Manager | NixOS | Standalone |
| --- | --- | --- | | --- | --- | --- |
| [Flake + Home-Manager](./docs/reference.md#home-manager) | [NixOS](./docs/reference.md#nixos) | [Standalone](./docs/reference.md#standalone) | | [Flake + Home-Manager](./docs/reference.md#home-manager) | [NixOS](./docs/reference.md#nixos) | [Standalone](./docs/reference.md#standalone) |
# Hacking
This project is licensend under MIT. Only bugs should be filed in our [issue tracker](https://github.com/nix-community/nix-doom-emacs/issues).
The `PR wanted` label is for issues that we'd appreciate PRs for the most.
Contributions are welcome.

28
docs/faq.md
View File

@@ -1,22 +1,15 @@
| readme | reference | faq | | [readme](/README.md) | [reference](./reference.md)| faq |
| --- | --- | --- |
| [README.md](/README.md) | [docs/reference.md](./reference.md)| this document |
# FAQ # Frequently Asked Questions
This is more meant as a "Fully Anticipated Questions" than a "Frequently Asked Questions", as they're anticipated as common pitfalls to using NDE.
## I am new to Nix. Is this the only way to use Doom Emacs with Nix/NixOS? ## 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 could just follow the instructions on the [Doom Emacs GitHub repository](https://github.com/doomemacs/doomemacs) to get a working setup. 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.
## 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 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. ## How do I add a non-(M)ELPA dependency to a package's build?
In an imperative environment, Doom updates can break Emacs with no easy way to roll back. You'd usually need to do this when a (M)ELPA pakage needs some package to exist on your system, like `git` for example.
nix-doom-emacs moves the moving parts of your Emacs installation into the Nix build sandbox.
## How do I add a native dependency to a package's build?
You should use the `emacsPackagesOverlay` attribute. Here's an example that installs `magit-delta`, which depends on Git: You should use the `emacsPackagesOverlay` attribute. Here's an example that installs `magit-delta`, which depends on Git:
@@ -33,8 +26,9 @@ programs.doom-emacs = {
## How do I add a package that's only on GitHub (or any Git frontend) ## How do I add a package that's only on GitHub (or any Git frontend)
This is the question you need if your Doom configuration errors with `Package not available`. `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) 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 requires a few more lines, but it isn't by any means difficult. For an example, this installs `idris2-mode` which isn't on (M)ELPA, but is hosted on GitHub: 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 ```nix
programs.doom-emacs = { programs.doom-emacs = {
@@ -43,7 +37,7 @@ programs.doom-emacs = {
idris2-mode = self.trivialBuild { idris2-mode = self.trivialBuild {
pname = "idris2-mode"; pname = "idris2-mode";
ename = "idris2-mode"; ename = "idris2-mode";
version = "0.0.0"; version = "unstable-2022-09-21";
buildInputs = [ self.prop-menu ]; buildInputs = [ self.prop-menu ];
src = pkgs.fetchFromGitHub { src = pkgs.fetchFromGitHub {
owner = "idris-community"; owner = "idris-community";
@@ -58,9 +52,9 @@ programs.doom-emacs = {
## nix-doom-emacs isn't working if I set DOOMDIR or EMACSDIR ## nix-doom-emacs isn't working if I set DOOMDIR or EMACSDIR
You shouldn't do that. nix-doom-emacs' home-manager module only writes `~/.emacs.d/init.el` in your `$HOME`, which points to the Nix store. 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. 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.
## I'm on MacOS and it says "Too many files open"! ## It erros with "Too many files open"!
Running `ulimit -S -n 2048` will fix it for the duration of your shell session. Running `ulimit -S -n 2048` will fix it for the duration of your shell session.
For a more permanent solution, NixOS has [`security.pam.loginLimits`](https://search.nixos.org/options?channel=22.05&from=0&size=50&sort=relevance&type=packages&query=security.pam.loginLimits) For a more permanent solution, NixOS has [`security.pam.loginLimits`](https://search.nixos.org/options?channel=22.05&from=0&size=50&sort=relevance&type=packages&query=security.pam.loginLimits)

23
docs/reference.md
View File

@@ -1,18 +1,13 @@
| readme | reference | faq | | [readme](/README.md) | reference | [faq](./faq.md) |
| --- | --- | --- |
| [README.md](/README.md) | this document | [docs/faq.md](./faq.md) |
# nix-doom-emacs reference # nix-doom-emacs reference
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). Only bugs should be filed in our [issue tracker](https://github.com/nix-community/nix-doom-emacs/issues).
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. 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 very obscure issues. 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 # Getting Started
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: 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. `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.
@@ -218,6 +213,16 @@ 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.
## trivialBuild and co ## trivialBuild and co
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, if you're confused about it's usage here. You can use it to build e.g. local packages or packages hosted on Git repositories. It is not a nix-doom-emacs tool. It's also in a family of functions in Nixpkgs which are made to build Emacs packages. Such as: 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, if you're confused about it's usage here. You can use it to build e.g. local packages or packages hosted on Git repositories. It is not a nix-doom-emacs tool. It's also in a family of functions in Nixpkgs which are made to build Emacs packages. Such as:
@@ -225,3 +230,7 @@ Though beyond the scope of this document, [`trivialBuild`](https://github.com/Ni
[`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. [`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), and [`melpaBuild`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/emacs/elpa.nix): Those are self-explanatory. To find examples of how they're used, you'll unfortunately have to [search Nixpkgs](https://github.com/NixOS/nixpkgs/search) for them. Luckily, the way they're used in Nixpkgs is very simple. [`elpaBuild`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/emacs/elpa.nix), and [`melpaBuild`](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/emacs/elpa.nix): Those are self-explanatory. To find examples of how they're used, you'll unfortunately have to [search Nixpkgs](https://github.com/NixOS/nixpkgs/search) for them. Luckily, the way they're used in Nixpkgs is very simple.
# 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).