From badae09b3ea2069526440202f77e7175fcd055cb Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Thu, 8 Sep 2022 21:42:54 +0300 Subject: [PATCH 01/21] Documentation overhaul --- README.md | 120 +----------------------------------------- docs/README.md | 139 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/faq.md | 122 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 263 insertions(+), 118 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/faq.md diff --git a/README.md b/README.md index 974124d..d240718 100644 --- a/README.md +++ b/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) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..18471de --- /dev/null +++ b/docs/README.md @@ -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 + ]; + # ... +} +``` diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..968022e --- /dev/null +++ b/docs/faq.md @@ -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. + From 3d51e18ae3bdc7c79a149859a05fbac4e9fec63d Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Mon, 12 Sep 2022 23:13:18 +0300 Subject: [PATCH 02/21] fix reviews --- README.md | 4 ++++ docs/README.md | 22 +++++++++++++++++----- docs/faq.md | 21 +++++++++++++++++---- 3 files changed, 38 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index d240718..4cf22c1 100644 --- a/README.md +++ b/README.md @@ -17,5 +17,9 @@ 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. +# Quick Start + +If you're impatient, you can run ``nix run github:nix-community/nix-doom-emacs``. If you want to use it more extensively, then you should continue reading [the documentation](./docs) + # Documentation To know how to use Nix-Doom-Emacs, and to fix other issues, check the [documentation](./docs) diff --git a/docs/README.md b/docs/README.md index 18471de..53de48e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,14 +1,20 @@ # 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. +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 Nix and Emacs (also Emacs Lisp) before using this project, and users should expect to have to debug things. + +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. +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`](https://github.com/radian-software/straight.el), the declarative package manager used by Doom Emacs. + +Before using Nix-Doom-Emacs, make sure to read [`nix-straight.el`'s README'](https://github.com/radian-software/straight.el) and that you understand the limitations. If you're not aware yet, then: -#### **WARNING**: HERE BE DRAGONS! THIS IS A FRAGILE PROJECT +#### **WARNING**: HERE BE DRAGONS! This project expects fairly advanced and experienced users. # Getting Started @@ -88,9 +94,9 @@ in { ``` -## Standalone +## NixOS -Using Nix-Doom-Emacs standalone isn't recommended, especially if you're a beginner. +Using Nix-Doom-Emacs without Home-Manager isn't recommended, especially if you're a beginner. `File: flake.nix` ```nix @@ -137,3 +143,9 @@ Using Nix-Doom-Emacs standalone isn't recommended, especially if you're a beginn # ... } ``` + +For what it's worth, you can see all overridable parameters of Nix-Doom-Emacs in [default.nix](../default.nix). + +## Standalone + +This is the least recommended method. diff --git a/docs/faq.md b/docs/faq.md index 968022e..bd245f9 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -93,16 +93,24 @@ idris2-repl.el:29:2: Error: Cannot open load file: No such file or directory, pr The way to fix it is by just adding the dependency it's complaining about. +Though, not all packages will complain very clearly about missing dependencies or really any issue. The best way to know how to get around this is to know how to debug Nix packages and derivations. Tools like `nix build`, `nix repl`, and `nix log` are your friend. Especially if you want to debug another person's configuration, or your own Nix-Doom-Emacs configuration without needing to `nixos-rebuild` it, then `nix build` is very useful. + +For an example, if a person is using Home-Manager+NixOS, then you can build their configuration via `nix build $CONFIG_PATH_HERE#nixosConfigurations.nixos.config.home-manager.users.$USER_HERE.programs.doom-emacs.package`. You need to replace `$CONFIG_PATH_HERE` with the path (like `.` if it's in the current directory), and `$USER_HERE` with the user. This could fail, and if it does, it'll tell you to use the `nix log` command to look at the full log. This will be important. + +For the `nix repl` command, it could be very useful for debugging as well. To know how to use it, I suggest [nix pills](https://nixos.org/guides/nix-pills/index.html), and to look at [the nix manual](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-repl.html) + ## 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: +If you're not, and you're using a standalone method (NixOS only without home-manager/nix-darwin) instead, you'll need: ```nix services.emacs = { enable = true; - package = inputs.doom-emacs.packages.${system}.doom-emacs; + package = inputs.doom-emacs.packages.${system}.doom-emacs.override { + doomPrivateDir = ./doom; + }; }; ``` @@ -110,7 +118,13 @@ 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. +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. 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: + +[`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. + +For what it's worth, this will not be the last time you muddle around in the Nixpkgs code to understand how to use something. The NixOS project is known to have very bad documentation, and unfortunately the code may be your only way to understand some things. ## Help! Nix-Doom-Emacs isn't working if I set DOOMDIR or EMACSDIR @@ -119,4 +133,3 @@ You shouldn't do that. The only thing that Nix-Doom-Emacs writes in your $HOME i # Help! on MacOS, it says "Too many files open"! Running `ulimit -S -n 2048` will fix it for the duration of your shell session. - From aa9c518c03b38d0084577946534ce7c3aea7ee78 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Tue, 13 Sep 2022 00:05:32 +0300 Subject: [PATCH 03/21] improve phrasing --- README.md | 9 +++++++- docs/README.md | 59 +++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 59 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 4cf22c1..0070156 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,14 @@ compatible with the `doom-emacs` requirements. # Quick Start -If you're impatient, you can run ``nix run github:nix-community/nix-doom-emacs``. If you want to use it more extensively, then you should continue reading [the documentation](./docs) +If you're impatient, you can run: + +``` +$ nix run github:nix-community/nix-doom-emacs +``` + +To use this project more extensively, you should read the documentation. + # Documentation To know how to use Nix-Doom-Emacs, and to fix other issues, check the [documentation](./docs) diff --git a/docs/README.md b/docs/README.md index 53de48e..d912b4f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,8 +1,8 @@ # Documentation for Nix-Doom-Emacs -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 Nix and Emacs (also Emacs Lisp) before using this project, and users should expect to have to debug things. +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 before using this project. -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 encounter any issues that make it unusable 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. @@ -10,11 +10,7 @@ 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`](https://github.com/radian-software/straight.el), the declarative package manager used by Doom Emacs. -Before using Nix-Doom-Emacs, make sure to read [`nix-straight.el`'s README'](https://github.com/radian-software/straight.el) and that you understand the limitations. - -If you're not aware yet, then: - -#### **WARNING**: HERE BE DRAGONS! This project expects fairly advanced and experienced users. +Before using Nix-Doom-Emacs, make sure to read [`nix-straight.el`'s README'](https://github.com/nix-community/nix-straight.el), and that you understand the consequences. # Getting Started @@ -148,4 +144,51 @@ For what it's worth, you can see all overridable parameters of Nix-Doom-Emacs in ## Standalone -This is the least recommended method. +This is the least recommended method. This uses the `devShell` (or `nix-shell` feature if you're using non-flakes, which is not recommended) feature of Nix. + +### 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 { } }: + +let + repo = pkgs.fetchFromGitHub { + owner = "nix-community"; + repo = "nix-doom-emacs"; + rev = ""; + sha256 = ""; + }; + nix-doom-emacs = pkgs.callPackage (import repo) { + doomPrivateDir = ./doom.d; + }; +in +pkgs.mkShell { + buildInputs = [ nix-doom-emacs ]; +} +``` From eca2c6e4f3c3d320cb92e311778a9a1dbb409478 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Tue, 13 Sep 2022 00:10:14 +0300 Subject: [PATCH 04/21] add faq for #4 --- docs/README.md | 4 ++-- docs/faq.md | 14 +++++++++++++- 2 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index d912b4f..1539adf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -148,7 +148,7 @@ This is the least recommended method. This uses the `devShell` (or `nix-shell` f ### Flake -``` nix +```nix { description = "nix-doom-emacs shell"; @@ -174,7 +174,7 @@ This is the least recommended method. This uses the `devShell` (or `nix-shell` f ``` ### Non-Flake -``` nix +```nix { pkgs ? import { } }: let diff --git a/docs/faq.md b/docs/faq.md index bd245f9..09385bd 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -130,6 +130,18 @@ For what it's worth, this will not be the last time you muddle around in the Nix 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"! +## Help! on MacOS, it says "Too many files open"! Running `ulimit -S -n 2048` will fix it for the duration of your shell session. + +## How do I use emacs-overlay's emacs with Nix-Doom-Emacs? + +This is very simple. you just use the `emacsPackage` attribute after applying `emacs-overlay` to your Nixpkgs. something like: + +```nix +programs.doom-emacs = { + enable = true; + doomPrivateDir = ./doom; + emacsPackage = pkgs.emacsPgtkNativeComp; # I used the native comp pgtk as an example +} +``` From 984b9d9d81a080d66be3afa77b0dbe49b1db4439 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Tue, 13 Sep 2022 00:17:37 +0300 Subject: [PATCH 05/21] add faq for imperative doom emacs --- docs/faq.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index 09385bd..421f045 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,6 +1,10 @@ # 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. +## 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. + ## 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. @@ -139,7 +143,7 @@ Running `ulimit -S -n 2048` will fix it for the duration of your shell session. This is very simple. you just use the `emacsPackage` attribute after applying `emacs-overlay` to your Nixpkgs. something like: ```nix -programs.doom-emacs = { +programs.doom-emacs = { enable = true; doomPrivateDir = ./doom; emacsPackage = pkgs.emacsPgtkNativeComp; # I used the native comp pgtk as an example From 9e52ac8227a7d80bc4ea165531f77599cc396acb Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Tue, 13 Sep 2022 00:23:08 +0300 Subject: [PATCH 06/21] improve quickstart --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 0070156..2310974 100644 --- a/README.md +++ b/README.md @@ -19,13 +19,14 @@ compatible with the `doom-emacs` requirements. # Quick Start -If you're impatient, you can run: +If you want to get a taste of Nix-Doom-Emacs, you can run: ``` $ nix run github:nix-community/nix-doom-emacs ``` -To use this project more extensively, you should read the documentation. +Which will run Nix-Doom-Emacs with an example configuration. +Continue to [the documentation](./docs) to learn how to customise your setup further to your needs. # Documentation From 9f5910542f56e08839e6b5fa8b821ff101363815 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Tue, 13 Sep 2022 00:52:24 +0300 Subject: [PATCH 07/21] better configs --- docs/README.md | 79 +++++++++++++++----------------------------------- docs/faq.md | 4 +-- 2 files changed, 26 insertions(+), 57 deletions(-) diff --git a/docs/README.md b/docs/README.md index 1539adf..8ae29cd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,43 +33,28 @@ The Doom configuration will be referred to as `./doom.d` in these snippets. You 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; + }: { + nixosConfigurations.exampleHost = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; modules = [ - ./default.nix home-manager.nixosModules.home-manager { - home-manager.users.exampleUser.imports = [ ./home.nix ]; + home-manager.users.exampleUser = { ... }: { + imports = [ nix-doom-emacs.hmModule ]; + programs.doom-emacs = { + enable = true; + doomPrivateDir = ./doom; # Directory containing your config.el, init.el + # and packages.el files + }; + }; } ]; }; }; } - -``` - -`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 @@ -92,8 +77,6 @@ in { ## NixOS -Using Nix-Doom-Emacs without Home-Manager isn't recommended, especially if you're a beginner. - `File: flake.nix` ```nix { @@ -105,18 +88,22 @@ Using Nix-Doom-Emacs without Home-Manager isn't recommended, especially if you'r outputs = { self, nixpkgs, - lib, nix-doom-emacs, ... - }: - let - system = "x86_64-linux"; - specialArgs = { inherit inputs; }; - in { - nixosConfigurations.exampleHost = lib.nixosSystem { - inherit system specialArgs; + }: { + nixosConfigurations.exampleHost = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; modules = [ - ./default.nix + { + environment.systemPackages = + let + doom-emacs = inputs.nix-doom-emacs.packages.${system}.defaut.override { + doomPrivateDir = ./doom; + }; + in [ + doom-emacs + ]; + } # ... ]; }; @@ -124,28 +111,10 @@ Using Nix-Doom-Emacs without Home-Manager isn't recommended, especially if you'r } ``` -`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 - ]; - # ... -} -``` - For what it's worth, you can see all overridable parameters of Nix-Doom-Emacs in [default.nix](../default.nix). ## Standalone -This is the least recommended method. This uses the `devShell` (or `nix-shell` feature if you're using non-flakes, which is not recommended) feature of Nix. - ### Flake ```nix diff --git a/docs/faq.md b/docs/faq.md index 421f045..adcbe43 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -7,11 +7,11 @@ Nope! Doom Emacs is still perfectly usable imperatively. In fact, the very autho ## 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. +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 install my favourite package? -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: ```nix programs.doom-emacs = { From c3fc23c8ed5d4c9b5b884318f2fcac62d722bc33 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Tue, 13 Sep 2022 00:55:20 +0300 Subject: [PATCH 08/21] nix-doom-emacs isn't Nix-Doom-Emacs --- README.md | 6 +++--- docs/README.md | 12 ++++++------ docs/faq.md | 12 ++++++------ 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 2310974..d22adf5 100644 --- a/README.md +++ b/README.md @@ -19,15 +19,15 @@ compatible with the `doom-emacs` requirements. # Quick Start -If you want to get a taste of Nix-Doom-Emacs, you can run: +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. +Which will run nix-doom-emacs with an example configuration. Continue to [the documentation](./docs) to learn how to customise your setup further to your needs. # Documentation -To know how to use Nix-Doom-Emacs, and to fix other issues, check the [documentation](./docs) +To know how to use nix-doom-emacs, and to fix other issues, check the [documentation](./docs) diff --git a/docs/README.md b/docs/README.md index 8ae29cd..3b4bd28 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,16 +1,16 @@ -# Documentation for Nix-Doom-Emacs +# Documentation for nix-doom-emacs -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 before using 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 before using this project. -If you encounter any issues that make it unusable 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 encounter any issues that make it unusable 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`](https://github.com/radian-software/straight.el), the declarative package manager used by Doom Emacs. +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`](https://github.com/radian-software/straight.el), the declarative package manager used by Doom Emacs. -Before using Nix-Doom-Emacs, make sure to read [`nix-straight.el`'s README'](https://github.com/nix-community/nix-straight.el), and that you understand the consequences. +Before using nix-doom-emacs, make sure to read [`nix-straight.el`'s README'](https://github.com/nix-community/nix-straight.el), and that you understand the consequences. # Getting Started @@ -111,7 +111,7 @@ in { } ``` -For what it's worth, you can see all overridable parameters of Nix-Doom-Emacs in [default.nix](../default.nix). +For what it's worth, you can see all overridable parameters of nix-doom-emacs in [default.nix](../default.nix). ## Standalone diff --git a/docs/faq.md b/docs/faq.md index adcbe43..537059a 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -7,7 +7,7 @@ Nope! Doom Emacs is still perfectly usable imperatively. In fact, the very autho ## 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. +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 install my favourite package? @@ -97,7 +97,7 @@ idris2-repl.el:29:2: Error: Cannot open load file: No such file or directory, pr The way to fix it is by just adding the dependency it's complaining about. -Though, not all packages will complain very clearly about missing dependencies or really any issue. The best way to know how to get around this is to know how to debug Nix packages and derivations. Tools like `nix build`, `nix repl`, and `nix log` are your friend. Especially if you want to debug another person's configuration, or your own Nix-Doom-Emacs configuration without needing to `nixos-rebuild` it, then `nix build` is very useful. +Though, not all packages will complain very clearly about missing dependencies or really any issue. The best way to know how to get around this is to know how to debug Nix packages and derivations. Tools like `nix build`, `nix repl`, and `nix log` are your friend. Especially if you want to debug another person's configuration, or your own nix-doom-emacs configuration without needing to `nixos-rebuild` it, then `nix build` is very useful. For an example, if a person is using Home-Manager+NixOS, then you can build their configuration via `nix build $CONFIG_PATH_HERE#nixosConfigurations.nixos.config.home-manager.users.$USER_HERE.programs.doom-emacs.package`. You need to replace `$CONFIG_PATH_HERE` with the path (like `.` if it's in the current directory), and `$USER_HERE` with the user. This could fail, and if it does, it'll tell you to use the `nix log` command to look at the full log. This will be important. @@ -122,7 +122,7 @@ You can now run `emacsclient -c` to connect to the daemon. ## What is `trivialBuild`? -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. 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. 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: [`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. @@ -130,15 +130,15 @@ Though beyond the scope of this document, [`trivialBuild`](https://github.com/Ni For what it's worth, this will not be the last time you muddle around in the Nixpkgs code to understand how to use something. The NixOS project is known to have very bad documentation, and unfortunately the code may be your only way to understand some things. -## Help! Nix-Doom-Emacs isn't working if I set DOOMDIR or EMACSDIR +## 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. +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. -## How do I use emacs-overlay's emacs with Nix-Doom-Emacs? +## How do I use emacs-overlay's emacs with nix-doom-emacs? This is very simple. you just use the `emacsPackage` attribute after applying `emacs-overlay` to your Nixpkgs. something like: From 7e2e54e56970b789bdee692360f4085d3f5dcf7e Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Wed, 14 Sep 2022 01:27:18 +0300 Subject: [PATCH 09/21] improve documentation --- README.md | 16 ++-- docs/README.md | 163 --------------------------------- docs/faq.md | 110 +++-------------------- docs/reference.md | 225 ++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 243 insertions(+), 271 deletions(-) delete mode 100644 docs/README.md create mode 100644 docs/reference.md diff --git a/README.md b/README.md index d22adf5..0f4511a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +
faqreadmereference
[docs/faq.md](./faq.md)this document[docs/reference.md](./docs/reference.md)
+ # nix-doom-emacs | | Status | @@ -9,6 +11,8 @@ Nix expression to install and configure [doom-emacs](https://github.com/doomemacs/doomemacs). +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 pre-installed based on an existing `~/.doom.d` directory. @@ -19,15 +23,9 @@ compatible with the `doom-emacs` requirements. # Quick Start -If you want to get a taste of nix-doom-emacs, you can run: - -``` -$ nix run github:nix-community/nix-doom-emacs -``` - +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. -Continue to [the documentation](./docs) to learn how to customise your setup further to your needs. +Pick which setup you're using here (if you're not using NixOS or Home-Manager, then you should use standalone): +Home-Manager
NixOSStandalone
[Flake + Home-Manager](./docs/reference.md#flake--home-manager)[NixOS](./docs/reference.md#nixos)[Standalone](./docs/reference.md#standalone)
-# Documentation -To know how to use nix-doom-emacs, and to fix other issues, check the [documentation](./docs) diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 3b4bd28..0000000 --- a/docs/README.md +++ /dev/null @@ -1,163 +0,0 @@ -# Documentation for nix-doom-emacs - -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 before using this project. - -If you encounter any issues that make it unusable 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`](https://github.com/radian-software/straight.el), the declarative package manager used by Doom Emacs. - -Before using nix-doom-emacs, make sure to read [`nix-straight.el`'s README'](https://github.com/nix-community/nix-straight.el), and that you understand the consequences. - -# 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, - 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; # 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 ]; -} -``` - - -## 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 { - system = "x86_64-linux"; - modules = [ - { - environment.systemPackages = - let - doom-emacs = inputs.nix-doom-emacs.packages.${system}.defaut.override { - doomPrivateDir = ./doom; - }; - in [ - doom-emacs - ]; - } - # ... - ]; - }; - }; -} -``` - -For what it's worth, 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 { } }: - -let - repo = pkgs.fetchFromGitHub { - owner = "nix-community"; - repo = "nix-doom-emacs"; - rev = ""; - sha256 = ""; - }; - nix-doom-emacs = pkgs.callPackage (import repo) { - doomPrivateDir = ./doom.d; - }; -in -pkgs.mkShell { - buildInputs = [ nix-doom-emacs ]; -} -``` diff --git a/docs/faq.md b/docs/faq.md index 537059a..2b2ff82 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,3 +1,5 @@ +
faqreadmereference
this document[README.md](/README.md)[docs/reference.md](./docs/reference.md)
+ # 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. @@ -9,7 +11,10 @@ Nope! Doom Emacs is still perfectly usable imperatively. In fact, the very autho 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 install my favourite package? +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. + +## 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: @@ -24,7 +29,7 @@ programs.doom-emacs = { }; ``` -### But what if my package is from a Git source, and isn't on ELPA? +## How do I add a package that's only on GitHub (or any Git frontend) 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: @@ -48,104 +53,11 @@ programs.doom-emacs = { }; ``` -### Help! My favourite package doesn't work after adding it in! +## nix-doom-emacs isn't working if I set DOOMDIR or EMACSDIR -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: +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. -**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. - -Though, not all packages will complain very clearly about missing dependencies or really any issue. The best way to know how to get around this is to know how to debug Nix packages and derivations. Tools like `nix build`, `nix repl`, and `nix log` are your friend. Especially if you want to debug another person's configuration, or your own nix-doom-emacs configuration without needing to `nixos-rebuild` it, then `nix build` is very useful. - -For an example, if a person is using Home-Manager+NixOS, then you can build their configuration via `nix build $CONFIG_PATH_HERE#nixosConfigurations.nixos.config.home-manager.users.$USER_HERE.programs.doom-emacs.package`. You need to replace `$CONFIG_PATH_HERE` with the path (like `.` if it's in the current directory), and `$USER_HERE` with the user. This could fail, and if it does, it'll tell you to use the `nix log` command to look at the full log. This will be important. - -For the `nix repl` command, it could be very useful for debugging as well. To know how to use it, I suggest [nix pills](https://nixos.org/guides/nix-pills/index.html), and to look at [the nix manual](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-repl.html) - -## 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. - -If you're not, and you're using a standalone method (NixOS only without home-manager/nix-darwin) instead, you'll need: - -```nix -services.emacs = { - enable = true; - package = inputs.doom-emacs.packages.${system}.doom-emacs.override { - doomPrivateDir = ./doom; - }; -}; -``` - -You can now run `emacsclient -c` to connect to the daemon. - -## What is `trivialBuild`? - -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. 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: - -[`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. - -For what it's worth, this will not be the last time you muddle around in the Nixpkgs code to understand how to use something. The NixOS project is known to have very bad documentation, and unfortunately the code may be your only way to understand some things. - -## 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"! +## I'm on MacOS and it says "Too many files open"! Running `ulimit -S -n 2048` will fix it for the duration of your shell session. - -## How do I use emacs-overlay's emacs with nix-doom-emacs? - -This is very simple. you just use the `emacsPackage` attribute after applying `emacs-overlay` to your Nixpkgs. something like: - -```nix -programs.doom-emacs = { - enable = true; - doomPrivateDir = ./doom; - emacsPackage = pkgs.emacsPgtkNativeComp; # I used the native comp pgtk as an example -} -``` +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) diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 0000000..f9c229d --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,225 @@ +
faqreadmereference
[docs/faq.md](./faq.md)[README.md](/README.md)this document
+ +# 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. + +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. + +# 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. + +## 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 { + system = "x86_64-linux"; + modules = [ + { + environment.systemPackages = + let + doom-emacs = inputs.nix-doom-emacs.packages.${system}.defaut.override { + doomPrivateDir = ./doom.d; + }; + in [ + doom-emacs + ]; + } + # ... + ]; + }; + }; +} +``` + +For what it's worth, 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 { } }: + +let + repo = pkgs.fetchFromGitHub { + owner = "nix-community"; + repo = "nix-doom-emacs"; + rev = ""; + sha256 = ""; + }; + 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 only without home-manager/nix-darwin) 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) + +You can use the `emacsPackage` attribute after applying `emacs-overlay` to your Nixpkgs: + +```nix +programs.doom-emacs = { + enable = true; + doomPrivateDir = ./doom.d; + emacsPackage = pkgs.emacsPgtkNativeComp; +} +``` + +For Non-HM: + +```nix +let + # ... + doom-emacs = nix-doom-emacs.packages.${system}.default.override { + doomPrivateDir = ./doom.d; + emacsPackage = pkgs.emacsPgtkNativeComp; + }; +in { + # ... +} +``` + +And for Non-Flake: +```nix +let + # ... + nix-doom-emacs = pkgs.callPackage (import repo) { + doomPrivateDir = ./doom.d; + emacsPackage = pkgs.emacsPgtkNativeComp + }; +in { + # ... +} +``` + +## 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: + +[`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. From 7a12ba91d57187d66ce7589aa77d321954d7a3f9 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Wed, 14 Sep 2022 01:34:34 +0300 Subject: [PATCH 10/21] improve tables --- README.md | 10 +++++++++- docs/faq.md | 4 +++- docs/reference.md | 5 ++++- 3 files changed, 16 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0f4511a..007f651 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,12 @@ -
faqreadmereference
[docs/faq.md](./faq.md)this document[docs/reference.md](./docs/reference.md)
+| faq | readme | reference | +| --- | --- | --- | +| [docs/faq.md](./faq.md) | this document | [docs/refrence.md](./refrence.md) | + + + + + + # nix-doom-emacs diff --git a/docs/faq.md b/docs/faq.md index 2b2ff82..78338ff 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,4 +1,6 @@ -
faqreadmereference
this document[README.md](/README.md)[docs/reference.md](./docs/reference.md)
+| faq | readme | reference | +| --- | --- | --- | +| this document | [README.md](/README.md) | [docs/refrence.md](./refrence.md) | # 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. diff --git a/docs/reference.md b/docs/reference.md index f9c229d..a5a1e24 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,4 +1,7 @@ -
faqreadmereference
[docs/faq.md](./faq.md)[README.md](/README.md)this document
+| faq | readme | reference | +| --- | --- | --- | +| [docs/faq.md](./faq.md) | [README.md](/README.md) | this document | + # nix-doom-emacs reference From 2bf0097a0abb885935d024f722185a7c0e6b8c07 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Wed, 14 Sep 2022 01:35:42 +0300 Subject: [PATCH 11/21] fix broken link --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 007f651..5c3fdae 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -| faq | readme | reference | -| --- | --- | --- | -| [docs/faq.md](./faq.md) | this document | [docs/refrence.md](./refrence.md) | +| faq | readme | reference | +| --- | --- | --- | +| [docs/faq.md](./docs/faq.md) | this document | [docs/refrence.md](./docs/refrence.md) | From 68f7600950c21d241369e780ad89cea99a502e3d Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Wed, 14 Sep 2022 01:40:25 +0300 Subject: [PATCH 12/21] fix broken links and improve tables --- README.md | 12 +++--------- docs/reference.md | 7 +++---- 2 files changed, 6 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 5c3fdae..3fe9da8 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,6 @@ -| faq | readme | reference | -| --- | --- | --- | -| [docs/faq.md](./docs/faq.md) | this document | [docs/refrence.md](./docs/refrence.md) | - - - - - - +| readme | reference | faq | +| --- | --- | --- | +| this document | [docs/reference.md](./docs/reference.md)| [docs/faq.md](./docs/faq.md) | # nix-doom-emacs diff --git a/docs/reference.md b/docs/reference.md index a5a1e24..88ebe58 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,7 +1,6 @@ -| faq | readme | reference | -| --- | --- | --- | -| [docs/faq.md](./faq.md) | [README.md](/README.md) | this document | - +| readme | reference | faq | +| --- | --- | --- | +| [README.md](/README.md) | this document | [docs/faq.md](./faq.md) | # nix-doom-emacs reference From 20bd0eda9c58ad4bb157866edb2394254fa56f0f Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Wed, 14 Sep 2022 01:42:49 +0300 Subject: [PATCH 13/21] i forgot to write the faq.md file --- docs/faq.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 78338ff..88a44c0 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,6 +1,6 @@ -| faq | readme | reference | -| --- | --- | --- | -| this document | [README.md](/README.md) | [docs/refrence.md](./refrence.md) | +| readme | reference | faq | +| --- | --- | --- | +| [README.md](/README.md) | [docs/reference.md](./reference.md)| this document | # 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. From a9a713e6195abcaa12270a822e9524b80a5ad4df Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Wed, 14 Sep 2022 01:50:08 +0300 Subject: [PATCH 14/21] improve setup table --- README.md | 10 ++++++---- docs/faq.md | 2 +- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3fe9da8..cc1a427 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -| readme | reference | faq | -| --- | --- | --- | -| this document | [docs/reference.md](./docs/reference.md)| [docs/faq.md](./docs/faq.md) | +| readme | reference | faq | +| --- | --- | --- | +| this document | [docs/reference.md](./docs/reference.md)| [docs/faq.md](./docs/faq.md) | # nix-doom-emacs @@ -29,5 +29,7 @@ If you want to get a taste of nix-doom-emacs, you can run ``nix run github:nix-c Which will run nix-doom-emacs with an example configuration. Pick which setup you're using here (if you're not using NixOS or Home-Manager, then you should use standalone): -Home-Manager
NixOSStandalone
[Flake + Home-Manager](./docs/reference.md#flake--home-manager)[NixOS](./docs/reference.md#nixos)[Standalone](./docs/reference.md#standalone)
+| Home-Manager | NixOS | Standalone | +| --- | --- | --- | +| [Flake + Home-Manager](./docs/reference.md#flake--home-manager) | [NixOS](./docs/reference.md#nixos) | [Standalone](./docs/reference.md#standalone) | diff --git a/docs/faq.md b/docs/faq.md index 88a44c0..b7b70ec 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,6 +1,6 @@ | readme | reference | faq | | --- | --- | --- | -| [README.md](/README.md) | [docs/reference.md](./reference.md)| this document | +| [README.md](/README.md) | [docs/reference.md](./reference.md)| this document | # 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. From aa5171992ee3c271b977f2987e8445b2a5482e1e Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Wed, 14 Sep 2022 01:54:04 +0300 Subject: [PATCH 15/21] i forgot to change the setup table to use the updated home-manager --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cc1a427..796b7ad 100644 --- a/README.md +++ b/README.md @@ -32,4 +32,4 @@ Pick which setup you're using here (if you're not using NixOS or Home-Manager, t | Home-Manager | NixOS | Standalone | | --- | --- | --- | -| [Flake + Home-Manager](./docs/reference.md#flake--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) | From 45cab4da22baf12e07309adfd3fa6486778e52d8 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Thu, 15 Sep 2022 13:34:37 +0300 Subject: [PATCH 16/21] less fluff in getting started --- docs/reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference.md b/docs/reference.md index 88ebe58..d38a43a 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -12,7 +12,7 @@ Currently, `nix-straight.el` only extracts package names and uses [`emacs-overla # Getting Started -To get started, we suggest these methods. They are ordered from most suggested to least suggested. +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. From 1a524776a4402745e6ddf40253f1c6a33f0c8cd1 Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Fri, 16 Sep 2022 01:13:01 +0300 Subject: [PATCH 17/21] talk about the "package not available" error --- docs/faq.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/faq.md b/docs/faq.md index b7b70ec..77409d5 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -33,7 +33,8 @@ programs.doom-emacs = { ## How do I add a package that's only on GitHub (or any Git frontend) -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: +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) +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: ```nix programs.doom-emacs = { From 5952ea8b87ff7abb2310322e095c98c8096570ad Mon Sep 17 00:00:00 2001 From: Mon Aaraj Date: Wed, 21 Sep 2022 20:08:03 +0300 Subject: [PATCH 18/21] resolve reviews --- README.md | 17 ++++++++++------- docs/faq.md | 28 +++++++++++----------------- docs/reference.md | 23 ++++++++++++++++------- 3 files changed, 37 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 796b7ad..9c0a3a8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,4 @@ -| readme | reference | faq | -| --- | --- | --- | -| this document | [docs/reference.md](./docs/reference.md)| [docs/faq.md](./docs/faq.md) | +| readme | [reference](./docs/reference.md)| [faq](./docs/faq.md) | # 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) | | 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 -[doom-emacs](https://github.com/doomemacs/doomemacs). - -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. +nix-doom-emacs (abbreviated as NDE) provides a customisable Nix derivation for [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. The expression builds a `doom-emacs` distribution with dependencies 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 | | --- | --- | --- | | [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. diff --git a/docs/faq.md b/docs/faq.md index 77409d5..0e79df8 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,22 +1,15 @@ -| readme | reference | faq | -| --- | --- | --- | -| [README.md](/README.md) | [docs/reference.md](./reference.md)| this document | +| [readme](/README.md) | [reference](./reference.md)| faq | -# 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. +# 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 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. -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'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: @@ -33,8 +26,9 @@ programs.doom-emacs = { ## 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) -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: +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 = { @@ -43,7 +37,7 @@ programs.doom-emacs = { idris2-mode = self.trivialBuild { pname = "idris2-mode"; ename = "idris2-mode"; - version = "0.0.0"; + version = "unstable-2022-09-21"; buildInputs = [ self.prop-menu ]; src = pkgs.fetchFromGitHub { owner = "idris-community"; @@ -58,9 +52,9 @@ programs.doom-emacs = { ## 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. 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) diff --git a/docs/reference.md b/docs/reference.md index d38a43a..ad3366c 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,18 +1,13 @@ -| readme | reference | faq | -| --- | --- | --- | -| [README.md](/README.md) | this document | [docs/faq.md](./faq.md) | +| [readme](/README.md) | reference | [faq](./faq.md) | # 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. -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 -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. @@ -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 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. [`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). From dd63c54651d42d7b220f8ab2432029ae17a1e136 Mon Sep 17 00:00:00 2001 From: Thiago Kenji Okada Date: Sat, 29 Oct 2022 17:43:47 +0100 Subject: [PATCH 19/21] Improve docs --- README.md | 11 +++++------ docs/faq.md | 5 ++--- docs/reference.md | 30 +++++++++++++++++------------- 3 files changed, 24 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 9c0a3a8..36e717a 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -| readme | [reference](./docs/reference.md)| [faq](./docs/faq.md) | +
**readme**[reference](./docs/reference.md)[faq](./docs/faq.md)
# nix-doom-emacs @@ -8,8 +8,7 @@ | 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) | -nix-doom-emacs (abbreviated as NDE) provides a customisable Nix derivation for [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 (abbreviated as NDE) provides a customisable Nix derivation for [Doom Emacs](https://github.com/doomemacs/doomemacs). The expression builds a `doom-emacs` distribution with dependencies pre-installed based on an existing `~/.doom.d` directory. @@ -30,9 +29,9 @@ Pick which setup you're using here (if you're not using NixOS or Home-Manager, t | --- | --- | --- | | [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. +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. +Also, talk to us in the [Matrix Chat](https://matrix.to/#/#doom-emacs:nixos.org) to discuss ideas for future improvements. Contributions are welcome. diff --git a/docs/faq.md b/docs/faq.md index 0e79df8..24103c6 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,4 +1,4 @@ -| [readme](/README.md) | [reference](./reference.md)| faq | +
[readme](../README.md)[reference](./reference.md)**faq**
# Frequently Asked Questions @@ -54,7 +54,6 @@ programs.doom-emacs = { 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 erros with "Too many files open"! +## It errors with "Too many files open"! 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) diff --git a/docs/reference.md b/docs/reference.md index ad3366c..02cc06f 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,4 +1,4 @@ -| [readme](/README.md) | reference | [faq](./faq.md) | +
[readme](../README.md)**reference**[faq](./faq.md)
# nix-doom-emacs reference @@ -91,7 +91,7 @@ in { { environment.systemPackages = let - doom-emacs = inputs.nix-doom-emacs.packages.${system}.defaut.override { + doom-emacs = inputs.nix-doom-emacs.packages.${system}.default.override { doomPrivateDir = ./doom.d; }; in [ @@ -105,7 +105,7 @@ in { } ``` -For what it's worth, you can see all overridable parameters of nix-doom-emacs in [default.nix](../default.nix). +You can see all overridable parameters of nix-doom-emacs in [default.nix](../default.nix). ## Standalone @@ -159,9 +159,10 @@ pkgs.mkShell { # 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 only without home-manager/nix-darwin) instead, you'll need: +If you're not, and you're using a standalone method (NixOS/nix-darwin without Home-Manager) instead, you'll need: ```nix services.emacs = { @@ -174,19 +175,19 @@ services.emacs = { You can now run `emacsclient -c` to connect to the daemon. -## Custom Emacs derivations (i.e., pgtk, nativeComp) +## Custom Emacs derivations (i.e., PGTK, NativeComp) -You can use the `emacsPackage` attribute after applying `emacs-overlay` to your Nixpkgs: +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 = { +programs.doom-emacs = { enable = true; doomPrivateDir = ./doom.d; emacsPackage = pkgs.emacsPgtkNativeComp; } ``` -For Non-HM: +For standalone usage with Flakes: ```nix let @@ -200,7 +201,8 @@ in { } ``` -And for Non-Flake: +And for non-Flakes usage: + ```nix let # ... @@ -223,13 +225,15 @@ To update your Doom Emacs config, you simply rebuild your configuration. For exa 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 +## 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, 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. 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. +- [`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 -[`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. +To find examples of how they're used, try to [search nixpkgs](https://github.com/NixOS/nixpkgs/search) for usages of them. # Support From 4625b0de8534d33e53a0b6696343c584c2bbced3 Mon Sep 17 00:00:00 2001 From: Thiago Kenji Okada Date: Tue, 17 Jan 2023 18:57:03 +0000 Subject: [PATCH 20/21] Review fixes --- docs/reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/reference.md b/docs/reference.md index 02cc06f..e950728 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -19,7 +19,7 @@ In all of these methods, you'll need your Doom Emacs configuration. It should co ```nix { inputs = { - nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable" + 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"; }; @@ -85,13 +85,13 @@ in { nix-doom-emacs, ... }: { - nixosConfigurations.exampleHost = nixpkgs.lib.nixosSystem { + nixosConfigurations.exampleHost = nixpkgs.lib.nixosSystem rec { system = "x86_64-linux"; modules = [ { environment.systemPackages = let - doom-emacs = inputs.nix-doom-emacs.packages.${system}.default.override { + doom-emacs = nix-doom-emacs.packages.${system}.default.override { doomPrivateDir = ./doom.d; }; in [ @@ -183,7 +183,7 @@ If you're using the Home-Manager module, you can use the `emacsPackage` attribut programs.doom-emacs = { enable = true; doomPrivateDir = ./doom.d; - emacsPackage = pkgs.emacsPgtkNativeComp; + emacsPackage = pkgs.emacsPgtk; } ``` From 3067a7a6080bf57e31cd64c023dab494c10165da Mon Sep 17 00:00:00 2001 From: Thiago Kenji Okada Date: Tue, 17 Jan 2023 19:12:07 +0000 Subject: [PATCH 21/21] Fix tables --- README.md | 4 +++- docs/faq.md | 4 +++- docs/reference.md | 4 +++- 3 files changed, 9 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 36e717a..576d343 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -
**readme**[reference](./docs/reference.md)[faq](./docs/faq.md)
+| index | | | +| --- | --- | --- | +|**readme**|[reference](./docs/reference.md)|[faq](./docs/faq.md)| # nix-doom-emacs diff --git a/docs/faq.md b/docs/faq.md index 24103c6..941d774 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,4 +1,6 @@ -
[readme](../README.md)[reference](./reference.md)**faq**
+| index | | | +| --- | --- | --- | +|[readme](../README.md)|[reference](./docs/reference.md)|**faq**| # Frequently Asked Questions diff --git a/docs/reference.md b/docs/reference.md index e950728..296a136 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -1,4 +1,6 @@ -
[readme](../README.md)**reference**[faq](./faq.md)
+| index | | | +| --- | --- | --- | +|[readme](../README.md)|**reference**|[faq](./docs/faq.md)| # nix-doom-emacs reference