A thin wrapper around Nixpkgs emacs.pkgs.withPackages using the module system with some footguns¹ removed

nima provides mkNima function through a Nixpkgs overlay.

mkNima takes an attribute set as argument:

{
  module ? { },
  featuresDir ? null,
  collect ? collectAllNixFiles,
  rawOutput ? false
}

• module is a nima module.
• featuresDir is a directory containing nima features.
• collect is a function taking a directory and returning a list of nima feature file paths in that directory. It is used to collect nima feature files in featuresDir when featuresDir is not null. The default collect function collects all .nix files in the directory. featuresDir must be of type path when using the default collect function. You may find lib.fileset useful when writing your own collect function.
• rawOutput defaults to false and mkNima returns a configured Emacs. When rawOutput is true, mkNima returns the raw output of lib.evalModules, which is an attribute set. Taking config.finalPackage from that attribute set and you get a configured Emacs, which is exactly the return value of mkNima when rawOutput is false. Setting rawOutput to true is for advanced use cases such as debugging by inspecting values of nima options in nix repl and modifying an already nima-configured Emacs via extendModules.

See option documentation for available module options.

Each file under featuresDir directory configures a nima feature.

Each file is a nima module like this

# epub.nix
{ pkgs, ... }:

{
  features.epub = {
    elisp = "...";
    epkgs = epkgs: [
      epkgs.nov
      pkgs.epub2txt2
    ];
  };
}

The feature <name> in features.<name> is almost always the same as the file name with .nix stripped. For example, in the above file, the feature is epub and the file is named epub.nix. To reduce duplication, we can also write the above file like this

# epub.nix
{ thisFeature }:

{ pkgs, ... }:

{
  features.${thisFeature} = {
    elisp = "...";
    epkgs = epkgs: [
      epkgs.nov
      pkgs.epub2txt2
    ];
  };
}

Most of the time, each feature file contains only features.<name>. In that case, we can further simplify the above file like this

# epub.nix
{ pkgs, ... }:

{
  elisp = "...";
  epkgs = epkgs: [
    epkgs.nov
    pkgs.epub2txt2
  ];
}

Take a look at these annotated examples to get a feeling of what nima configurations look like and how to configure a nima feature.

Try out Emacsen configured by those examples using commands like

HOME=$(mktemp -d) nix run github:jian-lin/nima#exampleSimple

See detailed usage.

The author dogfoods nima and will make necessary changes in the future to keep nima working.

nima serves the author well, so presumably the author will not add new features. However, if there is a feature wanted by many people, the author may consider adding it. In addition, pull requests are welcome.

• Configure early-init.el: this cannot be done in nima, but you can do it outside of nima using things like systemd.tmpfiles NixOS module option
• Configure Emacs daemon service: this is beyond the scope of nima, which is configuring Emacs proper

• emacs.pkgs.withPackages of Nixpkgs
• programs.emacs of Home Manager
• emacsWithPackagesFromUsePackage of emacs-overlay

AGPL-3.0-or-later