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