From 51b6504c4714fab1bdcc5273d5d9a5e1acbaf8d9 Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Thu, 24 Oct 2024 21:13:46 -0300 Subject: [PATCH 1/6] emacsPackages: refactor update-from-overlay script The tasks executed by the update-from-overlay script are very useful for interactive as well as batch update sessions. Thinking about it, I refactored the whole thing: - The tasks are now functions kept in a file, `update-scripts-library.sh`. This file is meant to be sourced, so that the functions can be used in both batch and interactive environments. - The update-from-overlay script was rewritten accordingly. - Since Bash lacks serious data structures, I am using a JSON file as database. --- .../elisp-packages/elisp-archives-table.json | 32 +++++ .../emacs/elisp-packages/update-from-overlay | 52 ++------ .../elisp-packages/update-scripts-library.sh | 112 ++++++++++++++++++ 3 files changed, 155 insertions(+), 41 deletions(-) create mode 100644 pkgs/applications/editors/emacs/elisp-packages/elisp-archives-table.json create mode 100755 pkgs/applications/editors/emacs/elisp-packages/update-scripts-library.sh diff --git a/pkgs/applications/editors/emacs/elisp-packages/elisp-archives-table.json b/pkgs/applications/editors/emacs/elisp-packages/elisp-archives-table.json new file mode 100644 index 0000000000000..1d17105455a0b --- /dev/null +++ b/pkgs/applications/editors/emacs/elisp-packages/elisp-archives-table.json @@ -0,0 +1,32 @@ +{ + "elpa": { + "overlay_url": "https://raw.githubusercontent.com/nix-community/emacs-overlay/master/repos/elpa/elpa-generated.nix", + "generated_file": "elpa-generated.nix", + "nix_attribute": "emacsPackages.elpaPackages" + }, + "elpa-devel": { + "overlay_url": "https://raw.githubusercontent.com/nix-community/emacs-overlay/master/repos/elpa/elpa-devel-generated.nix", + "generated_file": "elpa-devel-generated.nix", + "nix_attribute": "emacsPackages.elpaDevelPackages" + }, + "melpa": { + "overlay_url": "https://raw.githubusercontent.com/nix-community/emacs-overlay/master/repos/melpa/recipes-archive-melpa.json", + "generated_file": "recipes-archive-melpa.json", + "nix_attribute": "emacsPackages.melpaPackages" + }, + "melpa-stable": { + "overlay_url": "https://raw.githubusercontent.com/nix-community/emacs-overlay/master/repos/melpa/recipes-archive-melpa.json", + "generated_file": "recipes-archive-melpa.json", + "nix_attribute": "emacsPackages.melpaStablePackages" + }, + "nongnu": { + "overlay_url": "https://raw.githubusercontent.com/nix-community/emacs-overlay/master/repos/nongnu/nongnu-generated.nix", + "generated_file": "nongnu-generated.nix", + "nix_attribute": "emacsPackages.nongnuPackages" + }, + "nongnu-devel": { + "overlay_url": "https://raw.githubusercontent.com/nix-community/emacs-overlay/master/repos/nongnu/nongnu-devel-generated.nix", + "generated_file": "nongnu-devel-generated.nix", + "nix_attribute": "emacsPackages.nongnuDevelPackages" + } +} diff --git a/pkgs/applications/editors/emacs/elisp-packages/update-from-overlay b/pkgs/applications/editors/emacs/elisp-packages/update-from-overlay index 5879f4e3eab56..2b4e90398895b 100755 --- a/pkgs/applications/editors/emacs/elisp-packages/update-from-overlay +++ b/pkgs/applications/editors/emacs/elisp-packages/update-from-overlay @@ -1,49 +1,19 @@ #!/usr/bin/env nix-shell #! nix-shell -i bash -p curl nix coreutils -set -euxo pipefail +set -euo pipefail -# This script piggybacks on the automatic code generation done by the nix-community emacs overlay -# You can use this to avoid running lengthy code generation jobs locally +# This script relies on the automatic code generation done by the emacs overlay +# kept by nix-community +# You can use this to avoid running time-consuming code generation jobs locally -export NIXPKGS_ALLOW_BROKEN=1 +source ./update-scripts-library.sh -download_change() { - local FILE_LOCATION="$1" +# The loops are unrolled as follows because either all packagesets should be +# updated, or none of them should. Therefore, if any of them fails, all the +# process should be aborted as soon as possible. - local BASEURL="https://raw.githubusercontent.com/nix-community/emacs-overlay/master/repos" +download_packagesets "elpa" "elpa-devel" "melpa" "nongnu" "nongnu-devel" - curl -s -O "${BASEURL}/${FILE_LOCATION}" -} +test_packagesets "elpa" "elpa-devel" "melpa" "melpa-stable" "nongnu" "nongnu-devel" -commit_change() { - local MESSAGE="$1" - local FILENAME="$2" - - git diff --exit-code "${FILENAME}" > /dev/null || \ - git commit -m "${MESSAGE}: updated $(date --iso) (from overlay)" -- "${FILENAME}" -} - -test_packageset(){ - local PKGSET="$1" - - nix-instantiate --show-trace ../../../../../ -A "emacs.pkgs.$PKGSET" -} - -download_change "elpa/elpa-generated.nix" -download_change "elpa/elpa-devel-generated.nix" -download_change "melpa/recipes-archive-melpa.json" -download_change "nongnu/nongnu-generated.nix" -download_change "nongnu/nongnu-devel-generated.nix" - -test_packageset "nongnuPackages" -test_packageset "nongnuDevelPackages" -test_packageset "elpaPackages" -test_packageset "elpaDevelPackages" -test_packageset "melpaStablePackages" -test_packageset "melpaPackages" - -commit_change "elpa-packages" "elpa-generated.nix" -commit_change "elpa-devel-packages" "elpa-devel-generated.nix" -commit_change "melpa-packages" "recipes-archive-melpa.json" -commit_change "nongnu-packages" "nongnu-generated.nix" -commit_change "nongnu-devel-packages" "nongnu-devel-generated.nix" +commit_packagesets "elpa" "elpa-devel" "melpa" "nongnu" "nongnu-devel" diff --git a/pkgs/applications/editors/emacs/elisp-packages/update-scripts-library.sh b/pkgs/applications/editors/emacs/elisp-packages/update-scripts-library.sh new file mode 100755 index 0000000000000..799cc515fe681 --- /dev/null +++ b/pkgs/applications/editors/emacs/elisp-packages/update-scripts-library.sh @@ -0,0 +1,112 @@ +#!/usr/bin/env bash + +# This is a basic library that concentrates the main tasks of bulk updating. +# It is meant to be `source`d, so that it can be used in both +# batch and interactive environments. + +# TODO: Bail out if any dependency is not found +# TODO: should we make this a nix-shell script? +# DEPENDENCIES=( "curl" "jq" "git" "nix" ) + +# Classic "where I am" block +# https://www.binaryphile.com/bash/2020/01/12/determining-the-location-of-your-script-in-bash.html +SCRIPT_DIR=$(cd $(dirname ${BASH_SOURCE[0]}); cd -P $(dirname $(readlink ${BASH_SOURCE[0]} || echo .)); pwd) + +# Since Bash is meager on data structures, let's use a JSON file and jq! +# The format is straightforward: +# archive_name : { overlay_url, generated_file, nix_attribute } +JSON_ARCHIVE_TABLE="${SCRIPT_DIR}/elisp-archives-table.json" + +function download_packagesets { + # Silent early-return when no argument is passed + if [[ "$#" == "0" ]]; then + return 0 + fi + + declare -a ARCHIVE_LIST + + # collect the command line arguments, bailing out when any of them is not recognized + while (( "$#" )); do + ARCHIVE_NAME="$1" + if [[ "$(jq "has(\"${ARCHIVE_NAME}\")" ${JSON_ARCHIVE_TABLE})" == "false" ]]; then + echo "${FUNCNAME[0]}: unknown package archive: ${ARCHIVE_NAME}" + return 1 + else + ARCHIVE_LIST+=( "${ARCHIVE_NAME}" ) + fi + shift + done + + pushd "${SCRIPT_DIR}" > /dev/null + for ARCHIVE_NAME in "${ARCHIVE_LIST[@]}"; do + URL=$(jq --raw-output ".\"${ARCHIVE_NAME}\".overlay_url" "${JSON_ARCHIVE_TABLE}") + echo "${FUNCNAME[0]}: ${ARCHIVE_NAME}..." + curl --silent --remote-name "${URL}" + echo "${FUNCNAME[0]}: ${ARCHIVE_NAME}: done!" + done + popd > /dev/null +} + +function test_packagesets { + # Silent early-return when no argument is passed + if [[ "$#" == "0" ]]; then + return 0 + fi + + declare -a ARCHIVE_LIST + + # collect the command line arguments, bailing out when any of them is not recognized + while (( "$#" )); do + ARCHIVE_NAME="$1" + if [[ "$(jq "has(\"${ARCHIVE_NAME}\")" ${JSON_ARCHIVE_TABLE})" == "false" ]]; then + echo "${FUNCNAME[0]}: unknown package archive: ${ARCHIVE_NAME}" + return 1 + else + ARCHIVE_LIST+=( "${ARCHIVE_NAME}" ) + fi + shift + done + + pushd "${SCRIPT_DIR}" > /dev/null + for ARCHIVE_NAME in "${ARCHIVE_LIST[@]}"; do + ATTRIBUTE=$(jq --raw-output ".\"${ARCHIVE_NAME}\".nix_attribute" "${JSON_ARCHIVE_TABLE}") + echo "${FUNCNAME[0]}: ${ATTRIBUTE}..." + NIXPKGS_ALLOW_BROKEN=1 nix-instantiate --show-trace ../../../../../ -A "${ATTRIBUTE}" + echo "${FUNCNAME[0]}: ${ATTRIBUTE}: done!" + done + popd > /dev/null +} + +function commit_packagesets { + # Silent early-return when no argument is passed + if [[ "$#" == "0" ]]; then + return 0 + fi + + declare -a ARCHIVE_LIST + + while (( "$#" )); do + ARCHIVE_NAME="$1" + if [[ "$(jq "has(\"${ARCHIVE_NAME}\")" ${JSON_ARCHIVE_TABLE})" == "false" ]]; then + echo "${FUNCNAME[0]}: unknown package archive: ${ARCHIVE_NAME}" + return 1 + else + ARCHIVE_LIST+=( "${ARCHIVE_NAME}" ) + fi + shift + done + + pushd "${SCRIPT_DIR}" > /dev/null + for ARCHIVE_NAME in "${ARCHIVE_LIST[@]}"; do + ATTRIBUTE=$(jq --raw-output ".\"${ARCHIVE_NAME}\".nix_attribute" "${JSON_ARCHIVE_TABLE}") + FILE=$(jq --raw-output ".\"${ARCHIVE_NAME}\".generated_file" "${JSON_ARCHIVE_TABLE}") + if [[ "$(git diff --exit-code "${FILE}" > /dev/null)" == "0" ]]; then + echo "${FUNCNAME[0]}: ${FILE}..." + git commit -m "${ATTRIBUTE}: updated at $(date --iso)" -- "${FILE}" + echo "${FUNCNAME[0]}: ${FILE}: done!" + else + echo "${FUNCNAME[0]}: ${FILE} was not modified" + fi + done + popd > /dev/null +} From 810d232fb1702b76ff3b45f69a090538f6c43907 Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Fri, 25 Oct 2024 22:05:12 -0300 Subject: [PATCH 2/6] emacsPackages: combine elpa-* and nongnu-* update scripts They are identical except for the parameters they use. Let's merge them in a single script. Now they can be called via `./update-package-sets `. --- .../editors/emacs/elisp-packages/update-elpa | 6 --- .../emacs/elisp-packages/update-elpa-devel | 6 --- .../emacs/elisp-packages/update-nongnu | 6 --- .../emacs/elisp-packages/update-nongnu-devel | 6 --- .../emacs/elisp-packages/update-package-sets | 54 +++++++++++++++++++ 5 files changed, 54 insertions(+), 24 deletions(-) delete mode 100755 pkgs/applications/editors/emacs/elisp-packages/update-elpa delete mode 100755 pkgs/applications/editors/emacs/elisp-packages/update-elpa-devel delete mode 100755 pkgs/applications/editors/emacs/elisp-packages/update-nongnu delete mode 100755 pkgs/applications/editors/emacs/elisp-packages/update-nongnu-devel create mode 100755 pkgs/applications/editors/emacs/elisp-packages/update-package-sets diff --git a/pkgs/applications/editors/emacs/elisp-packages/update-elpa b/pkgs/applications/editors/emacs/elisp-packages/update-elpa deleted file mode 100755 index 6cf3bafd24e16..0000000000000 --- a/pkgs/applications/editors/emacs/elisp-packages/update-elpa +++ /dev/null @@ -1,6 +0,0 @@ -#! /usr/bin/env nix-shell -#! nix-shell --show-trace ./emacs2nix.nix -i bash - -output="elpa-generated.nix" -elpa-packages.sh --names $EMACS2NIX/names.nix -o "$output" -nixfmt "$output" diff --git a/pkgs/applications/editors/emacs/elisp-packages/update-elpa-devel b/pkgs/applications/editors/emacs/elisp-packages/update-elpa-devel deleted file mode 100755 index 356d93167af88..0000000000000 --- a/pkgs/applications/editors/emacs/elisp-packages/update-elpa-devel +++ /dev/null @@ -1,6 +0,0 @@ -#! /usr/bin/env nix-shell -#! nix-shell --show-trace ./emacs2nix.nix -i bash - -output="elpa-devel-generated.nix" -elpa-devel-packages.sh --names $EMACS2NIX/names.nix -o "$output" -nixfmt "$output" diff --git a/pkgs/applications/editors/emacs/elisp-packages/update-nongnu b/pkgs/applications/editors/emacs/elisp-packages/update-nongnu deleted file mode 100755 index 9a4b20716c152..0000000000000 --- a/pkgs/applications/editors/emacs/elisp-packages/update-nongnu +++ /dev/null @@ -1,6 +0,0 @@ -#! /usr/bin/env nix-shell -#! nix-shell --show-trace ./emacs2nix.nix -i bash - -output="nongnu-generated.nix" -nongnu-packages.sh --names $EMACS2NIX/names.nix -o "$output" -nixfmt "$output" diff --git a/pkgs/applications/editors/emacs/elisp-packages/update-nongnu-devel b/pkgs/applications/editors/emacs/elisp-packages/update-nongnu-devel deleted file mode 100755 index a1f5f950d4387..0000000000000 --- a/pkgs/applications/editors/emacs/elisp-packages/update-nongnu-devel +++ /dev/null @@ -1,6 +0,0 @@ -#! /usr/bin/env nix-shell -#! nix-shell --show-trace ./emacs2nix.nix -i bash - -output="nongnu-devel-generated.nix" -nongnu-devel-packages.sh --names $EMACS2NIX/names.nix -o "$output" -nixfmt "$output" diff --git a/pkgs/applications/editors/emacs/elisp-packages/update-package-sets b/pkgs/applications/editors/emacs/elisp-packages/update-package-sets new file mode 100755 index 0000000000000..299ac414919ae --- /dev/null +++ b/pkgs/applications/editors/emacs/elisp-packages/update-package-sets @@ -0,0 +1,54 @@ +#! /usr/bin/env nix-shell +#! nix-shell --show-trace ./emacs2nix.nix -i bash + +usage(){ + cat<<-EOF +Usage: update-package-sets args +args can be at least one from: elpa-devel, elpa, nongnu-devel, nongnu. +EOF +} + +update_set(){ + local PKGSET="$1" + + local output="${PKGSET}-generated.nix" + local script="${PKGSET}-packages.sh" + + eval "${script} --names ${EMACS2NIX}/names.nix -o ${output}" + nixfmt "${output}" +} + +main(){ + local SETS=( ) + + while (( $# )); do + case $1 in + "elpa-devel" | "elpa" | "nongnu-devel" | "nongnu") + # Do not include duplicates + if [[ ! ${SETS[@]} =~ $1 ]]; then + SETS+=( "$1" ) + fi + shift + ;; + "melpa" | "melpa-stable") + # Let's warn the user of the correct script and go on + echo "This script does not generate the MELPA package set." + echo "Use update-melpa script instead." + shift + ;; + *) + echo "Unknown package set: $1" + usage + exit 1 + ;; + esac + done + + for SET in "${SETS[@]}"; do + echo "${SET}: updating..." + update_set "${SET}" + echo "${SET}: updated" + done +} + +main "$@" From 703d094c9f9bb3d1e1e95e8346e20b551d73f5d3 Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Sun, 27 Oct 2024 10:40:37 -0300 Subject: [PATCH 3/6] emacsPackages: use better SCRIPT_DIR detection in update scripts --- pkgs/applications/editors/emacs/elisp-packages/update | 8 +++++--- .../editors/emacs/elisp-packages/update-manual | 6 ++++-- 2 files changed, 9 insertions(+), 5 deletions(-) diff --git a/pkgs/applications/editors/emacs/elisp-packages/update b/pkgs/applications/editors/emacs/elisp-packages/update index 02701fb546d95..e9f649c8aa50e 100755 --- a/pkgs/applications/editors/emacs/elisp-packages/update +++ b/pkgs/applications/editors/emacs/elisp-packages/update @@ -1,10 +1,12 @@ #!/usr/bin/env bash set -euo pipefail -SCRIPT_DIR="$( cd "$(dirname "$0")" ; pwd -P )" -cd "$SCRIPT_DIR" +# Classic "where I am" block +# https://www.binaryphile.com/bash/2020/01/12/determining-the-location-of-your-script-in-bash.html +SCRIPT_DIR=$(cd $(dirname ${BASH_SOURCE[0]}); cd -P $(dirname $(readlink ${BASH_SOURCE[0]} || echo .)); pwd) +cd "${SCRIPT_DIR}" ./update-from-overlay ./update-manual -git commit -m "emacs.pkgs.manualPackages: $(date --iso)" -- . +git commit -m "emacsPackages.manualPackages: updated at $(date --iso) (non-interactively)" -- . diff --git a/pkgs/applications/editors/emacs/elisp-packages/update-manual b/pkgs/applications/editors/emacs/elisp-packages/update-manual index 3b199eecc3d2b..1a83f14b7b74b 100755 --- a/pkgs/applications/editors/emacs/elisp-packages/update-manual +++ b/pkgs/applications/editors/emacs/elisp-packages/update-manual @@ -1,7 +1,9 @@ #!/usr/bin/env bash set -euo pipefail -SCRIPT_DIR="$( cd "$(dirname "$0")" ; pwd -P )" -cd "$SCRIPT_DIR" +# Classic "where I am" block +# https://www.binaryphile.com/bash/2020/01/12/determining-the-location-of-your-script-in-bash.html +SCRIPT_DIR=$(cd $(dirname ${BASH_SOURCE[0]}); cd -P $(dirname $(readlink ${BASH_SOURCE[0]} || echo .)); pwd) +cd "${SCRIPT_DIR}" nix-build --no-out-link update-manual.nix | xargs -n 1 -P $(nproc) bash -c From c690385f1861f7ba6e7daddb297607ca8992cc3c Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Thu, 24 Oct 2024 21:17:27 -0300 Subject: [PATCH 4/6] 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 91abc49f4c2b3..2e78744f7e4a2 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 aec8f1446f11b99d3494838813e2e9a593caa4a3 Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Thu, 24 Oct 2024 21:40:41 -0300 Subject: [PATCH 5/6] doc/packages/emacs.section.md: reword --- doc/packages/emacs.section.md | 51 ++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/doc/packages/emacs.section.md b/doc/packages/emacs.section.md index 2ced251f3e46a..c1d0d20044574 100644 --- a/doc/packages/emacs.section.md +++ b/doc/packages/emacs.section.md @@ -1,8 +1,24 @@ # 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 +36,19 @@ 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 custom package can be installed like any other one, via `nix-env -iA myEmacs`. + +However, this expression merely installs the package, without configuring their parts. +Such a configuration requires an Elisp file crafted 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/`. +Emacs loads this file automatically when it starts. + +Let's modify the example above: ```nix { @@ -97,9 +125,24 @@ 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: +Emacs accepts the command-line argument `--no-init-file` (short form `-q`) +to not load the init files. + +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. -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`. +A complete and pervasive override for such a package can be done via +`overrideScope`. ```nix let From 538db05e878bc77e6d1486a828004248099d47cf Mon Sep 17 00:00:00 2001 From: Anderson Torres Date: Sun, 17 Nov 2024 08:22:29 -0300 Subject: [PATCH 6/6] 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..7b6307303d416 --- /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