diff options
Diffstat (limited to 'overlays/patches/emacs/overlay/README.org')
| -rw-r--r-- | overlays/patches/emacs/overlay/README.org | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/overlays/patches/emacs/overlay/README.org b/overlays/patches/emacs/overlay/README.org new file mode 100644 index 000000000000..5bb0974ada65 --- /dev/null +++ b/overlays/patches/emacs/overlay/README.org @@ -0,0 +1,203 @@ +* 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 =emacsGit= and =emacs-unstable=. +=emacsGit= 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 =emacsGit-nox= and =emacs-unstable-nox= +if you wish to have Emacs built without X dependencies. +=emacsPgtk= 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.emacsGit; + + # By default emacsWithPackagesFromUsePackage will only pull in + # packages with `:ensure`, `:ensure t` or `:ensure <package name>`. + # 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 <nixpkgs> { overlays = [ (import ./.) ]; }); emacsGit' +#+end_src + +* Community + +** Matrix chat +[[https://matrix.to/#/#emacs:nixos.org][Nix Emacs]] + +# LocalWords: EXWM NixOS emacsGit +# LocalWords: SRC nixpkgs builtins fetchTarball url |