twist-archiver

This flake provides a function which lets you build an archive for offline installation of Emacs configuration.

Unlike nix-bundle, it doesn’t produce a self-contained archive. Rather, you can import the configuration as well as its dependencies using nix-store --import into your Nix store, so you can use your Emacs configuration even in an environment where you can’t clone repositories from GitHub. You still require Nix, but you don’t require full network connectivity. You can just download an archive and import it into the Nix store.

How it works

The Nix application produces a zstd-compressed archive that contains two files:

• A NAR archive containing everything needed to run your Emacs configuration.
• A text file that contains a list of store paths that should be installed to your Nix profile. It exposes executables (most notably bin/emacs) and the init file share/emacs/init.el (and early-init.el if you specify one).

The former one can be imported into your Nix store using nix-store --import. The latter can be installed using nix-env -i or nix profile install.

Configuration

The flake provides an overlay which you can integrate into nixpkgs.

First add an input to flake.nix:

{
  inputs.twist-archiver.url = "github:emacs-twist/twist-archiver";

  outputs = {nixpkgs, ...} @ inputs:
    ...
}

Then add an overlay:

let
  pkgs = import nixpkgs {
    inherit system;
    overlays = [
      inputs.emacs-twist.overlays.default
      inputs.twist-archiver.overlays.default
      ...
    ];
  }
in
   ...

Then you can use makeEmacsTwistArchive function which takes two arguments: an attribute set of options and a twist configuration derivation. An flake configuration example is as follows:

{
  packages = {
    inherit emacs-config;
    build-archive = pkgs.makeEmacsTwistArchive {
      # Name should be the same as the output name in the flake
      name = "build-archive";
      # Source of early-init.el (optional)
      earlyInitFile = ./early-init.el;
      # Name of the nar archive (optional)
      narName = "archive.nar";
      # Name of the zstd archive (optional)
      outName = "archive.tar.zstd";
      # Name of the manifest which is needed for hot reloading using twist.el
      # (optional)
      manifestName = "twist-manifest.json",
    } emacs-config;
  };
}

Usage

With the configuration above, you can build an archive using nix run command:

nix run .#build-archive

It produces archive.tar.zstd (or the name you specified as outName).

You can try it out in an isolated environment using Docker. Note that you don’t require Docker at all to extract from the archive:

docker run -ti -v $PWD:/data -w /data nixos/nix

You can uncompress the archive using zstd:

zstd -d archive.tar.zstd
zstdcat archive.tar.zstd | tar xf -

and import the configuration:

nix-store --import archive.nar

The archive also includes files.txt which contains a list of store paths to install:

xargs nix-env -i < files.txt

Create symbolic links to early-init.el and init.el installed to the Nix profile:

mkdir -p ~/.config/emacs
cd ~/.config/emacs
for file in init.el early-init.el twist-manifest.json; do
    ln -s ~/.nix-profile/share/emacs/$file
done

Now you can start Emacs with the imported configuration:

emacs -nw