Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nix-community/emacs-overlay

Bleeding edge emacs overlay [maintainer=@adisbladis]
https://github.com/nix-community/emacs-overlay

Last synced: 3 months ago
JSON representation

Bleeding edge emacs overlay [maintainer=@adisbladis]

Awesome Lists containing this project

README 

        
* Emacs overlay for Nixpkgs

** Quickstart

To get up and running quickly, add the following lines to your =/etc/nixos/configuration.nix=:



#+BEGIN_SRC nix

{config, pkgs, callPackage, ... }:

{

# ...



  services.emacs.package = pkgs.emacs-unstable;



  nixpkgs.overlays = [

    (import (builtins.fetchTarball {

      url = "https://github.com/nix-community/emacs-overlay/archive/master.tar.gz";

    }))

  ];



# ...

}

#+END_SRC



This configuration will enable this overlay, and define your system-wide emacs package as the =emacs-unstable= attribute it provides.



*NOTE:* Read the "Usage of the overlay" section below for further explanation of this configuration. This has the potential to break things, and will frequently trigger full source rebuilds of emacs.



If you want to enable daemon/server mode, add the following line to the same configuration:



#+BEGIN_SRC nix

services.emacs.enable = true;

#+END_SRC



It is recommended you read Nixpkgs and NixOS documentation on package overlays and overrides to familiarize yourself with the concepts:



 - https://nixos.wiki/wiki/Overlays

 - https://nixos.org/nixpkgs/manual/#chap-overlays



** Contents of the overlay



This overlay consists of two overlays: =emacs= and =package=.



You can use both of them as a whole overlay or only one of them.



*** =package= overlay



**** Elpa

Daily generations of Elpa.



**** Melpa / Melpa stable

Daily generations of Melpa & Melpa stable attribute sets.



**** EXWM & needed dependencies

This overlay provides fresh versions of EXWM and dependencies. This is

updated daily.



*** =emacs= overlay



**** Emacs from Git and latest (including pre-releases)

This overlay also provides two versions (latest from git) for Emacs. These

are updated daily.



These attributes are named =emacs-git= and =emacs-unstable=.

=emacs-git= is built from the latest =master= branch and =emacs-unstable= is built from the latest tag.



Emacs from git is not guaranteed stable and may break your setup at any

time, if it breaks you get to keep both pieces.



We also provide two attributes named =emacs-git-nox= and =emacs-unstable-nox=

if you wish to have Emacs built without X dependencies.

=emacs-pgtk= uses the experimental pgtk feature which supports Wayland natively.



**** Extra library functionality

This overlay comes with extra functions to generate an Emacs closure

from various types of dependency declaration. (These are abstractions

on top of =emacsWithPackages=.)



For example, =emacsWithPackagesFromUsePackage= adds packages which are

required in a user's config via =use-package= or =leaf=.



#+BEGIN_SRC nix

  { pkgs, ... }:

  {

    environment.systemPackages = [

      (pkgs.emacsWithPackagesFromUsePackage {

        # Your Emacs config file. Org mode babel files are also

        # supported.

        # NB: Config files cannot contain unicode characters, since

        #     they're being parsed in nix, which lacks unicode

        #     support.

        # config = ./emacs.org;

        config = ./emacs.el;



        # Whether to include your config as a default init file.

        # If being bool, the value of config is used.

        # Its value can also be a derivation like this if you want to do some

        # substitution:

        #   defaultInitFile = pkgs.substituteAll {

        #     name = "default.el";

        #     src = ./emacs.el;

        #     inherit (config.xdg) configHome dataHome;

        #   };

        defaultInitFile = true;



        # Package is optional, defaults to pkgs.emacs

        package = pkgs.emacs-git;



        # By default emacsWithPackagesFromUsePackage will only pull in

        # packages with `:ensure`, `:ensure t` or `:ensure `.

        # Setting `alwaysEnsure` to `true` emulates `use-package-always-ensure`

        # and pulls in all use-package references not explicitly disabled via

        # `:ensure nil` or `:disabled`.

        # Note that this is NOT recommended unless you've actually set

        # `use-package-always-ensure` to `t` in your config.

        alwaysEnsure = true;



        # For Org mode babel files, by default only code blocks with

        # `:tangle yes` are considered. Setting `alwaysTangle` to `true`

        # will include all code blocks missing the `:tangle` argument,

        # defaulting it to `yes`.

        # Note that this is NOT recommended unless you have something like

        # `#+PROPERTY: header-args:emacs-lisp :tangle yes` in your config,

        # which defaults `:tangle` to `yes`.

        alwaysTangle = true;



        # Optionally provide extra packages not in the configuration file.

        extraEmacsPackages = epkgs: [

          epkgs.cask

        ];



        # Optionally override derivations.

        override = final: prev: {

          weechat = prev.melpaPackages.weechat.overrideAttrs(old: {

            patches = [ ./weechat-el.patch ];

          });

        };

      })

    ];

  }

#+END_SRC



Similarly, =emacsWithPackagesFromPackageRequires= adds packages which

are declared in a =.el= package file's =Package-Requires= header, which

can be handy for CI purposes:



#+BEGIN_SRC nix

...

let

  emacsForCI = pkgs.emacsWithPackagesFromPackageRequires {

    packageElisp = builtins.readFile ./flycheck.el;

    extraEmacsPackages = epkgs: [

      epkgs.package-lint

    ];

  };

pkgs.mkShell {

  buildInputs = [ emacsForCI ];

}

#+END_SRC



** Usage of the overlay

*** Latest master each rebuild

One way, and probably the most convenient way to pull in this overlay is by

just fetching the tarball of latest master on rebuild.



This has side-effects if packages breaks or things like that you may want

to be in control of which revision of the overlay you run.



Adding the overlay this way will extend your Emacs packages set to contain

the latest EXWM and dependencies from their respective master and make the

package =emacsGit= available. These of course change quite rapidly and will

cause compilation time.



#+BEGIN_SRC nix

{

  nixpkgs.overlays = [

    (import (builtins.fetchTarball {

      url = "https://github.com/nix-community/emacs-overlay/archive/master.tar.gz";

    }))

  ];

}

#+END_SRC



*** Binary cache

You will want to use the [[https://nix-community.org/#binary-cache][nix-community binary cache]]. Where the

overlay's build artefacts are pushed. See [[https://app.cachix.org/cache/nix-community][here]] for installation

instructions.



*** Install directly from the overlay

The repository is meant to be used as an overlay as is explained

above. Still, for experimental purposes, you might want to install a

package directly from the overlay. For example, you can install

=emacsGit= from a clone of this repository with the following command:



#+begin_src shell

  nix-build --expr 'with (import  { overlays = [ (import ./.) ]; }); emacs-git'

#+end_src



* Community



** Matrix chat

[[https://matrix.to/#/#emacs:nixos.org][Nix Emacs]]



#  LocalWords:  EXWM NixOS emacsGit

#  LocalWords:  SRC nixpkgs builtins fetchTarball url