From bb0b0177e9a7fe2a34649ead3ba0d92794d06fcd Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Thu, 24 Oct 2024 21:17:27 -0300 Subject: [PATCH 1/3] emacsPackages: remove update instructions from *-packages.nix files They will be gathered in a more fitting documentation. --- .../elisp-packages/elpa-devel-packages.nix | 24 ------------------ .../emacs/elisp-packages/elpa-packages.nix | 24 ------------------ .../emacs/elisp-packages/melpa-packages.nix | 25 ------------------- .../elisp-packages/nongnu-devel-packages.nix | 12 --------- .../emacs/elisp-packages/nongnu-packages.nix | 14 ----------- 5 files changed, 99 deletions(-) diff --git a/pkgs/applications/editors/emacs/elisp-packages/elpa-devel-packages.nix b/pkgs/applications/editors/emacs/elisp-packages/elpa-devel-packages.nix index 0db019dddb5c0..4ba4e46f87256 100644 --- a/pkgs/applications/editors/emacs/elisp-packages/elpa-devel-packages.nix +++ b/pkgs/applications/editors/emacs/elisp-packages/elpa-devel-packages.nix @@ -1,27 +1,3 @@ -/* - -# Updating - -To update the list of packages from ELPA, - -1. Run `./update-elpa-devel`. -2. Check for evaluation errors: - # "../../../../../" points to the default.nix from root of Nixpkgs tree - env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../../ -A emacs.pkgs.elpaDevelPackages -3. Run `git commit -m "elpa-devel-packages $(date -Idate)" -- elpa-devel-generated.nix` - -## Update from overlay - -Alternatively, run the following command: - -./update-from-overlay - -It will update both melpa and elpa packages using -https://github.com/nix-community/emacs-overlay. It's almost instantenous and -formats commits for you. - -*/ - { lib, pkgs, buildPackages }: self: let diff --git a/pkgs/applications/editors/emacs/elisp-packages/elpa-packages.nix b/pkgs/applications/editors/emacs/elisp-packages/elpa-packages.nix index 64c05ba3154e6..a553cd00d88a3 100644 --- a/pkgs/applications/editors/emacs/elisp-packages/elpa-packages.nix +++ b/pkgs/applications/editors/emacs/elisp-packages/elpa-packages.nix @@ -1,27 +1,3 @@ -/* - -# Updating - -To update the list of packages from ELPA, - -1. Run `./update-elpa`. -2. Check for evaluation errors: - # "../../../../../" points to the default.nix from root of Nixpkgs tree - env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../../ -A emacs.pkgs.elpaPackages -3. Run `git commit -m "elpa-packages $(date -Idate)" -- elpa-generated.nix` - -## Update from overlay - -Alternatively, run the following command: - -./update-from-overlay - -It will update both melpa and elpa packages using -https://github.com/nix-community/emacs-overlay. It's almost instantenous and -formats commits for you. - -*/ - { lib, pkgs, buildPackages }: self: let diff --git a/pkgs/applications/editors/emacs/elisp-packages/melpa-packages.nix b/pkgs/applications/editors/emacs/elisp-packages/melpa-packages.nix index 42e2340d72382..420fabbb15fef 100644 --- a/pkgs/applications/editors/emacs/elisp-packages/melpa-packages.nix +++ b/pkgs/applications/editors/emacs/elisp-packages/melpa-packages.nix @@ -1,28 +1,3 @@ -/* - -# Updating - -To update the list of packages from MELPA, - -1. Run `./update-melpa` -2. Check for evaluation errors: - # "../../../../../" points to the default.nix from root of Nixpkgs tree - env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate --show-trace ../../../../../ -A emacs.pkgs.melpaStablePackages - env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate --show-trace ../../../../../ -A emacs.pkgs.melpaPackages -3. Run `git commit -m "melpa-packages $(date -Idate)" recipes-archive-melpa.json` - -## Update from overlay - -Alternatively, run the following command: - -./update-from-overlay - -It will update both melpa and elpa packages using -https://github.com/nix-community/emacs-overlay. It's almost instantenous and -formats commits for you. - -*/ - let # Read ./recipes-archive-melpa.json in an outer let to make sure we only do this once. defaultArchive = builtins.fromJSON (builtins.readFile ./recipes-archive-melpa.json); diff --git a/pkgs/applications/editors/emacs/elisp-packages/nongnu-devel-packages.nix b/pkgs/applications/editors/emacs/elisp-packages/nongnu-devel-packages.nix index bba1f73f02afc..d79fd78daa592 100644 --- a/pkgs/applications/editors/emacs/elisp-packages/nongnu-devel-packages.nix +++ b/pkgs/applications/editors/emacs/elisp-packages/nongnu-devel-packages.nix @@ -1,15 +1,3 @@ -/* - # Updating - - To update the list of packages from nongnu devel (ELPA), - - 1. Run `./update-nongnu-devel`. - 2. Check for evaluation errors: - # "../../../../../" points to the default.nix from root of Nixpkgs tree - env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../../ -A emacs.pkgs.nongnuDevelPackages - 3. Run `git commit -m "nongnu-devel-packages $(date -Idate)" -- nongnu-devel-generated.nix` -*/ - { lib, pkgs, diff --git a/pkgs/applications/editors/emacs/elisp-packages/nongnu-packages.nix b/pkgs/applications/editors/emacs/elisp-packages/nongnu-packages.nix index 139bdaf6260a3..c37e1bf505ce4 100644 --- a/pkgs/applications/editors/emacs/elisp-packages/nongnu-packages.nix +++ b/pkgs/applications/editors/emacs/elisp-packages/nongnu-packages.nix @@ -1,17 +1,3 @@ -/* - -# Updating - -To update the list of packages from nongnu (ELPA), - -1. Run `./update-nongnu`. -2. Check for evaluation errors: - # "../../../../../" points to the default.nix from root of Nixpkgs tree - env NIXPKGS_ALLOW_BROKEN=1 nix-instantiate ../../../../../ -A emacs.pkgs.nongnuPackages -3. Run `git commit -m "nongnu-packages $(date -Idate)" -- nongnu-generated.nix` - -*/ - { lib, pkgs, buildPackages }: self: let From e249790808712ab14ea26bcdfd54c4c77f48bb83 Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Thu, 24 Oct 2024 21:40:41 -0300 Subject: [PATCH 2/3] doc/packages/emacs.section.md: reword --- doc/packages/emacs.section.md | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/doc/packages/emacs.section.md b/doc/packages/emacs.section.md index 2ced251f3e46a..6e9412eb6cf8a 100644 --- a/doc/packages/emacs.section.md +++ b/doc/packages/emacs.section.md @@ -1,8 +1,16 @@ # Emacs {#sec-emacs} +[Emacs](https://www.gnu.org/software/emacs/) is the advanced, extensible, customizable, self-documenting editor. + +At its core is an interpreter for Emacs Lisp (shortly, Elisp), a dialect of the Lisp programming language with extensions to support text editing. + ## Configuring Emacs {#sec-emacs-config} -The Emacs package comes with some extra helpers to make it easier to configure. `emacs.pkgs.withPackages` allows you to manage packages from ELPA. This means that you will not have to install that packages from within Emacs. For instance, if you wanted to use `company` `counsel`, `flycheck`, `ivy`, `magit`, `projectile`, and `use-package` you could use this as a `~/.config/nixpkgs/config.nix` override: +Nixpkgs provides a framework that leverages Emacs via Nix. + +`emacs.pkgs.withPackages` allows managing packages from various Elisp package repositories (ELPA, MELPA etc.) and even third-party stand-alone packages from Nix, without relying on Emacs to download and install them. + +For instance, by writing the code below at `~/.config/nixpkgs/config.nix`, the Elisp packages `company` `counsel`, `flycheck`, `ivy`,`magit`, `projectile`, and `use-package` are installed: ```nix { @@ -20,7 +28,16 @@ The Emacs package comes with some extra helpers to make it easier to configure. } ``` -You can install it like any other packages via `nix-env -iA myEmacs`. However, this will only install those packages. It will not `configure` them for us. To do this, we need to provide a configuration file. Luckily, it is possible to do this from within Nix! By modifying the above example, we can make Emacs load a custom config file. The key is to create a package that provides a `default.el` file in `/share/emacs/site-start/`. Emacs knows to load this file automatically when it starts. +This package can be installed like any other, via `nix-env -iA myEmacs`. + +However, this expression merely installs the package. It will not _configure_ them. +To do this, we need to provide a configuration file. + +Luckily, it is possible to do this from within Nix! + +By modifying the above example, we can make Emacs load a custom config file. +The key is to create a package that provides a `default.el` file in `/share/emacs/site-start/`. +Emacs loads this file automatically when it starts. ```nix { @@ -97,9 +114,14 @@ You can install it like any other packages via `nix-env -iA myEmacs`. However, t } ``` -This provides a fairly full Emacs start file. It will load in addition to the user's personal config. You can always disable it by passing `-q` to the Emacs command. +This provides a fairly full Emacs start file. It will be loaded in addition to the user's personal config. It is always possible to disable it, by passing `-q` as a command line argument to Emacs. + +Sometimes `emacs.pkgs.withPackages` is not enough, as this package set imposes some priorities over their packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). + +But it is not possible to control these priorities when some package is installed as a dependency. The overrides can be done on a per-package-basis, providing all the required dependencies manually. However this procedure is tedious and there is always a possibility that an unwanted dependency sneaks in through some other package. + +A complete and pervasive override for such a package can be done via `overrideScope`. -Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). But you can't control these priorities when some package is installed as a dependency. You can override it on a per-package-basis, providing all the required dependencies manually, but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package, you can use `overrideScope`. ```nix let From 2b4ac5126146f0703309cd872ce9d576627a8c2e Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Sun, 17 Nov 2024 08:22:29 -0300 Subject: [PATCH 3/3] doc/languages-frameworks/elisp.section.md: init --- doc/languages-frameworks/elisp.section.md | 124 ++++++++++++++++++++++ doc/languages-frameworks/index.md | 1 + 2 files changed, 125 insertions(+) create mode 100644 doc/languages-frameworks/elisp.section.md diff --git a/doc/languages-frameworks/elisp.section.md b/doc/languages-frameworks/elisp.section.md new file mode 100644 index 0000000000000..5ce022bb04f82 --- /dev/null +++ b/doc/languages-frameworks/elisp.section.md @@ -0,0 +1,124 @@ +# Emacs Lisp {#emacs-lisp} + +Since at least version 24, Emacs has a native package manager, `package.el`. +Since its inception, many Elisp packages were created by Emacs community at large, as well as Elisp package repositories. + + + +### Bulk Update {#sec-emacs-elisp-packages-bulk-update} + +The chief Elisp package repositories are [GNU ELPA](https://elpa.gnu.org/), [NonGNU ELPA](https://elpa.nongnu.org/), and [MELPA](https://melpa.org/). + +Nixpkgs provides a comprehensive infrastucture that leverages the contents of these Elisp repositories as Nix packages. This chapter describes the bulk-updating automation tooling. + +Inside the `emacs` directory lives the `elisp-packages` subdirectory. +Inside it we provide the following scripts: + +- `update-scripts_library.sh` + + This file serves as a library, containing useful functions to deal with bulk updates. + It can be `source`'d in both interactive and batch environments. + + This library provides the following functions: + + - `download_packageset` + + This function downloads from [`nix-community` Emacs Overlay](https://github.com/nix-community/emacs-overlay) the corresponding files. + + It accepts one argument. + This argument can assume one of the following values: + `elpa`, `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`. + + - `test_packageset` + + This function runs a simple test that instantiates the corresponding package set. + + It accepts one argument. + This argument can assume one of the following values: + `elpa`, `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`. + + - `commit_packageset` + + This function commits the corresponding package set to the Nixpkgs repository, writing a one-line descriptive commit message. + + It accepts two arguments. + + The first argument can assume one of the following values: `elpa`, + `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`. + The second argument is an optional free-form string used verbatim, describing the origin of the change being committed. + Its default value is `interactive session`. + +- `update-package-sets` + + This script updates the package sets passed to it as arguments. + + It accepts multiple arguments. + Each argument can assume one of the following values: + `elpa`, `elpa-devel`, `nongnu`, `nongnu-devel`. + +- `update-melpa` + + This script updates `recipes-archive-melpa.json`, a JSON file that describes the MELPA package set. + + It accepts no arguments. + +- `update-from-overlay` + + This script downloads all the packagesets from overlay, then tests and commits them. + + It accepts no arguments. +- `update-scripts_library.sh` + + This file serves as a library, containing useful functions to deal with bulk updates. + It can be `source`'d in both interactive and batch environments. + + This library provides the following functions: + + - `download_packageset` + + This function downloads from [`nix-community` Emacs Overlay](https://github.com/nix-community/emacs-overlay) the corresponding files. + + It accepts one argument. + This argument can assume one of the following values: + `elpa`, `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`. + + - `test_packageset` + + This function runs a simple test that instantiates the corresponding package set. + + It accepts one argument. + This argument can assume one of the following values: + `elpa`, `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`. + + - `commit_packageset` + + This function commits the corresponding package set to the Nixpkgs repository, writing a one-line descriptive commit message. + + It accepts two arguments. + + The first argument can assume one of the following values: `elpa`, + `elpa-devel`, `melpa`, `melpa-stable`, `nongnu`, `nongnu-devel`. + The second argument is an optional free-form string used verbatim, describing the origin of the change being committed. + Its default value is `interactive session`. + +- `update-package-sets` + + This script updates the package sets passed to it as arguments. + + It accepts multiple arguments. + Each argument can assume one of the following values: + `elpa`, `elpa-devel`, `nongnu`, `nongnu-devel`. + +- `update-melpa` + + This script updates `recipes-archive-melpa.json`, a JSON file that describes the MELPA package set. + + It accepts no arguments. + +- `update-from-overlay` + + This script downloads all the packagesets from overlay, then tests and commits them. + + It accepts no arguments. diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md index a8a13ce5b9e29..f56a29c5709ef 100644 --- a/doc/languages-frameworks/index.md +++ b/doc/languages-frameworks/index.md @@ -64,6 +64,7 @@ dart.section.md dhall.section.md dlang.section.md dotnet.section.md +elisp.section.md emscripten.section.md gnome.section.md go.section.md