Skip to content

Commit

Permalink
[s] doc/packages/emacs.section.md: reword
Browse files Browse the repository at this point in the history
  • Loading branch information
AndersonTorres committed Dec 14, 2024
1 parent 4e3d853 commit a544d0c
Showing 1 changed file with 33 additions and 12 deletions.
45 changes: 33 additions & 12 deletions doc/packages/emacs.section.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,24 @@
# Emacs {#sec-emacs}

[Emacs](https://www.gnu.org/software/emacs/) is the advanced, extensible, customizable, self-documenting editor.
[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.
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}

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.
`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:
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
{
Expand All @@ -30,15 +38,18 @@ For instance, by writing the code below at `~/.config/nixpkgs/config.nix`, the E

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.
However, this expression merely installs the package, without configuring them.
The configuration requires an Elisp file for this purpose.

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/`.
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.

Let's modify the example above:

```nix
{
packageOverrides = pkgs: with pkgs; rec {
Expand Down Expand Up @@ -114,14 +125,24 @@ Emacs loads this file automatically when it starts.
}
```

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`).
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:
Emacs accepts the command-line argument `--no-init-file` (short form `-q`)
to not load the init files.

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.
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`).

A complete and pervasive override for such a package can be done via `overrideScope`.
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`.

```nix
let
Expand Down

0 comments on commit a544d0c

Please sign in to comment.