lambdadog / emacs-nix

[DEPRECATED] Patched emacs that allows you to provide your emacs config via nix

emacs-nix

[ DEPRECATED -- I'm now of the opinion that managing your emacs config with Nix is an antipattern, and use borg. ]

A nix tool to enable providing your emacs config via Nix.

Usage

It's recommended to use the emacs-nix Cachix cache when using emacs-nix, although only if you're using the "golden" versions of emacs provided by this repository.

Using emacs-nix requires providing your emacs config as a well-formed emacs package derivation. This involves several things:

• Using provide statements, so your init registers a feature.
• Ensuring your derivation's pname is the same as your package name.
• Ensuring your package (and feature) name is the same as the filename of its entrypoint.

My personal convention is to call my init package config-init, which means:

• The derivation's pname is "config-init".
• The derivation's source tree contains config-init.el as its entrypoint.
• config-init.el contains (provide 'config-init) at the bottom of the file.

Then to use this config-init package with pure-GTK emacs with native compilation, and with an emacsDir in ~/.local/share/emacs/, assuming this package can be found at ./config-init, you would call emacsWithConfig as follows:

with emacsNix; emacsWithConfig emacsVersions.emacsPgtkGcc {
  emacsDir = "~/.local/share/emacs/";
  init = ep: ep.callPackage ./config-init {};
}

Fetching emacs-nix can be done however you wish. I personally use niv to manage my dependencies, but you can trivially also use fetchGit, fetchGitHub or fetchTarball.

"Golden" versions of emacs

emacs-nix provides several "golden" versions of emacs in the emacsVersions set, so called because their patched versions should always be cached via CI in the emacs-nix Cachix cache.

These golden versions are provided via emacs-nix's own Niv pins of both Nixpkgs and the nix-community emacs-overlay.

If desired, you may provide your own emacs derivation or override the existing ones. To do so, simply pass your emacs derivation to the emacsWithConfig function.

Note that emacsWithConfig functions via patches to emacs, therefore if you also patch emacs (specifically lisp/startup.el) there may be a chance of collisions. These patches support emacs 27, emacs 28, and the git master version of emacs as well as possible, although successful builds can only be guaranteed if you're using the provided golden versions. All overrides are also recommended to be based on said golden versions, to ensure the highest chance of successful builds.

emacs-nix's Issues

Add config scaffolding tools (or template)

My own emacs-config works alright for this, but it's not exactly UX to tell users to download your personal config and edit it.

"emacs-nix-config" derivation fails to build with emacs 27

As far as I can tell all other emacs* derivations allow a successful build but for emacs (emacs 27 from nixpkgs), I get this error:

$ nix-build .
these 3 derivations will be built:
  /nix/store/w6b1b7hv889n16qj2yx883bh20fv172f-emacs-emacs-nix-config.drv
  /nix/store/gippq3bd76nxyawzvsyg8ab2fi7qkkl4-emacs-packages-deps.drv
  /nix/store/g4299ada87x7yzvcx4qiiag9k7fapmpw-emacs-nix-with-config-27.2.drv
building '/nix/store/w6b1b7hv889n16qj2yx883bh20fv172f-emacs-emacs-nix-config.drv'...
unpacking sources
unpacking source archive /nix/store/0xhy0wkwgc2m50llf43ynyxdv8y2vmhz-emacs-nix-config-src
source root is emacs-nix-config-src
patching sources
configuring
no configure script, doing nothing
building
Symbol's function definition is void: make-closure
error: builder for '/nix/store/w6b1b7hv889n16qj2yx883bh20fv172f-emacs-emacs-nix-config.drv' failed with exit code 255
error: 1 dependencies of derivation '/nix/store/g4299ada87x7yzvcx4qiiag9k7fapmpw-emacs-nix-with-config-27.2.drv' failed to build

Update emacs master patches

Improve documentation

Perhaps the most important change to make overall.

Enable additional overrides to patched emacs derivation

There are other changes one might like to make to their emacs derivation that by not exposing it I'm causing to be no longer possible (for example, the emacs-nox derivations, in which one would compile emacs with no GUI support).

As part of #7 I'd like to add a way via the API to allow further overrides to the emacs derivation to enable these customizations.

Obviously some overrides (patches, incompatible with emacs-nix's) may break, but I'm willing to leave that possibility open so more advanced users can take advantage of the override system.

Expose `emacs-nix` in a way that allows for experienced nix user to provide their own nixpkgs/emacs-overlay

This will never be the primary goal of the project -- ensuring cache hits is more a goal than ultimate customizability of inputs, but it would be nice to expose a way for experienced users to eschew the usage of the specific versions I have pinned and choose to give up cache hits for customizability.

For inspiration, perhaps look to IOHK's haskell.nix? There are some differences, since haskell.nix doesn't depend on another overlay like we do, but it may be a solid starting point.

Improve API so using two different `emacs` versions in one invocation isn't possible

#4 was caused by accidentally using emacsPgtkGcc.packages.callPackage to call the init package of emacs.withConfig

Ideally, the way emacs-nix exposes its API should make this type of typo impossible.

Add CI task to automatically update `niv` pins

Ideally, this looks like:

• Update the niv pins
• Build
  • On success: Push to master
  • On failure:
    • If PR exists: Push to PR branch
    • If no PR exists: Open PR

Switch to markdown for README

GitHub's support for org documents is poorer than it should be, causing multiple issues with rendering that make documentation less clear than it could be.

Improve patch contribution workflow

Currently, these patches have to be generated manually using git patch-format. Ideally, I'd like to add some kind of script to the repository to both:

• Ease contribution to patches
• Ease avoiding patch conflicts with all supported versions of emacs

With most projects that involve patchsets, you're only patching against a singular version of the original project, but some inspiration could be taken regardless. PaperMC/Waterfall is an example of a project we could likely take inspiration from. They have a set of scripts in scripts/ that expose all necessary functionality to contribute easily to the project.

Refactor how `user-emacs-directory` is generated with `--batch`

It's not a problem for my usecase, but I could see it being one for others.

Improve building non-currentSystem emacsWithConfig derivations

Support was added by 6ef3550 but the code involved is currently incredibly ugly and I'm not happy with it.

I'd like to bring building for alternate systems up to a first class citizen in emacs-nix.

This may or may not require an API refactor. Perhaps we should require that emacs-nix is callPackage'd so we can hook into nixpkgs' pkgs.system infrastructure better, but it frankly doesn't feel quite right to me since emacs-nix is so self-contained to avoid cache misses.