From 5a0e882fd21893fb79a9a2205e96f37a951712cc Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Thu, 24 Oct 2024 21:40:41 -0300 Subject: [PATCH] [wip] doc/packages/emacs.section.md: add chapter about Emacs Lisp --- doc/packages/emacs.section.md | 139 +++++++++++++++++++++++++++++++++- 1 file changed, 137 insertions(+), 2 deletions(-) diff --git a/doc/packages/emacs.section.md b/doc/packages/emacs.section.md index 2ced251f3e46a..701f993f8be73 100644 --- a/doc/packages/emacs.section.md +++ b/doc/packages/emacs.section.md @@ -1,8 +1,15 @@ # Emacs {#sec-emacs} +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 allows configuring Emacs easily 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, so that you will not have to install them from within Emacs. +For instance, if you wanted to use `company` `counsel`, `flycheck`, `ivy`,`magit`, `projectile`, and `use-package` you could use this override in `~/.config/nixpkgs/config.nix`: ```nix { @@ -20,7 +27,10 @@ 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. +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. +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. ```nix { @@ -116,3 +126,128 @@ in ]) ``` } + +## Elisp Packages {#sec-emacs-elisp-packages} + +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.