diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 00dde3e..66fd74c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -22,39 +22,6 @@ Adapted from the [Contributor Covenant] and [The Carpentries Code of Conduct]: [Contributor Covenant]: https://github.com/EthicalSource/contributor_covenant/blob/cd7fcf684249786b7f7d47ba49c23a6bcb3233eb/content/version/2/1/code_of_conduct.md [The Carpentries Code of Conduct]: https://github.com/carpentries/docs.carpentries.org/blob/4691971d9f49544054410334140a4fd391a738da/topic_folders/policies/code-of-conduct.md -## Updating reference manuals - -With the current setup, the Nix manual hosted on nix.dev does not get updated automatically with new releases. -The following manual steps are required: - -- Regularly update the inputs to use the latest versions of the Nix release branches with `nix shell --run "niv update"` - - To avoid long build times, make sure Nix can be fetched from the cache. - If it doesn't, find the latest commit that is [built by Hydra](https://hydra.nixos.org/project/nix). For example, to pin Nix 2.18: - - ```bash - niv update nix_2-18 -r f5f4de6a550327b4b1a06123c2e450f1b92c73b6 - ``` - -- On each new Nix release: - - 1. Add the latest version in [`default.nix`](./default.nix). - For example, to add Nix 2.19: - - ```bash - niv add nixos/nix -n nix_2-19 -b 2.19-maintenance - ``` - - 2. Reference the latest version in [`source/reference/nix-manual.md`](./source/reference/nix-manual.md). - -- If an unstable or stable release of Nixpkgs adopt a new version of Nix, update the corresponding references here. - - Also update URLs to the the Nix manual to the version used by Nixpkgs unstable. - For example, if one wants to move from 2.18 to 2.19: - ```bash - sed -i 's#https://nix.dev/manual/nix/2.18/#https://nix.dev/manual/nix/2.19/#g' $(ls **/*.md) - ``` - ## What you can do ### You want to learn and use Nix? diff --git a/default.nix b/default.nix index 1cb0ec9..0007845 100644 --- a/default.nix +++ b/default.nix @@ -3,65 +3,128 @@ , }: let - pkgs = import inputs.nixpkgs { + pkgs = import inputs.nixpkgs-prev-stable { config = { }; overlays = [ (import ./overlay.nix) ]; inherit system; }; + lib = pkgs.lib; - nix-dev = pkgs.stdenv.mkDerivation { - name = "nix-dev"; - src = ./.; - nativeBuildInputs = with pkgs.python310.pkgs; [ - linkify-it-py - myst-parser - sphinx - sphinx-book-theme - sphinx-copybutton - sphinx-design - sphinx-notfound-page - sphinx-sitemap - ]; - buildPhase = '' - make html - ''; - installPhase = - let - # Various versions of the Nix manuals, grep for (nix-manual)= to find where they are displayed - # FIXME: This requires human interaction to update! See ./CONTRIBUTING.md for details. - releases = { - latest = "2.19"; - rolling = "2.18"; - stable = "2.18"; - prev-stable = "2.13"; - }; - inputName = version: pkgs.lib.strings.replaceStrings [ "." ] [ "-" ] version; - src = version: inputs."nix_${inputName version}"; - manual = version: (import (src version)).default.doc; - copy = version: '' - cp -Rf ${manual version}/share/doc/nix/manual/* $out/manual/nix/${version} + nix-dev = + let + # Various versions of the Nix manuals, grep for (nix-manual)= to find where they are displayed. + # XXX: With the current setup, the Nix manual hosted on nix.dev does not get updated automatically with new releases. + # The following manual steps are required: + # + # - Regularly update the inputs to use the latest versions of the Nix release branches with `nix shell --run "niv update"` + # + # To avoid long build times, make sure Nix can be fetched from the cache. + # If it doesn't, find the latest commit that is [built by Hydra](https://hydra.nixos.org/project/nix). For example, to update the latest Nix release to 2.20: + # + # ```bash + # niv update nix-stable -b 2.18-maintenance -r f5f4de6a550327b4b1a06123c2e450f1b92c73b6 + # ``` + # + # - On each new Nix release, update the `nix-latest` to the corresponding release branch: + # + # ```bash + # niv update nix-latest -b 2.20-maintenance + # ``` + # + # - On each new Nixpkgs release, update `nixpkgs-stable` and `nixpkgs-prev-stable` and the corresponding Nix versions: + # + # ```bash + # niv update nixpkgs-stable -b nixos-24.05 + # niv update nix-stable -b 2.19-maintenance + # niv update nixpkgs-prev-stable -b nixos-23.11 + # niv update nix-prev-stable -b 2.18-maintenance + # ``` + # + # It would be nice to have *efficient* automatic updates. + releases = rec { + nixpkgs-rolling = import inputs.nixpkgs-rolling { } // { inherit (nixpkgs-rolling.lib) version; }; + nixpkgs-stable = import inputs.nixpkgs-stable { } // { inherit (nixpkgs-stable.lib) version; }; + nixpkgs-prev-stable = import inputs.nixpkgs-prev-stable { } // { inherit (nixpkgs-prev-stable.lib) version; }; + nix-latest = (import inputs.nix-latest).default; + # TODO: to further simplify this and get Nix from Nixpkgs with all required files present, + # make a patch release of Nix after https://github.com/NixOS/nix/pull/9949 lands, + # and bump the respective version in the respective Nixpkgs `release-*` branch. + nix-rolling = (import inputs.nix-rolling).default; + nix-stable = (import inputs.nix-stable).default; + nix-prev-stable = (import inputs.nix-prev-stable).default; + }; + version = package: lib.versions.majorMinor package.version; + in + pkgs.stdenv.mkDerivation { + name = "nix-dev"; + src = ./.; + nativeBuildInputs = with pkgs.python310.pkgs; [ + linkify-it-py + myst-parser + sphinx + sphinx-book-theme + sphinx-copybutton + sphinx-design + sphinx-notfound-page + sphinx-sitemap + ]; + buildPhase = + let + nix-manual-index = + with lib.attrsets; + with lib.strings; + replaceStrings + (mapAttrsToList (release: _: "@${release}@") releases) + (mapAttrsToList (_: package: version package) releases) + (builtins.readFile ./source/reference/nix-manual.md); + in + '' + cp -f ${builtins.toFile "nix-manual.md" nix-manual-index} $TMP/nix.dev/source/reference/nix-manual.md + make html ''; - # add upstream page redirects of the form ` `, excluding comment lines and empty - redirects = version: '' - sed '/^#/d;/^$/d;s#^\(.*\) \(.*\) #/manual/nix/${version}\1 /manual/nix/${version}\2 #g' ${src version}/doc/manual/_redirects >> $out/_redirects + installPhase = + with lib.attrsets; + with lib.strings; + let + nix-releases = + let + package = name: elemAt (splitString "-" name) 0; + release = name: elemAt (splitString "-" name) 1; + filtered = filterAttrs (name: value: (package name) == "nix") releases; + in + mapAttrs' (name: value: { name = release name; inherit value; }) filtered; + # the same Nix version could appear in multiple Nixpkgs releases, + # but we want to copy each exactly once. + unique-version = + let + version-exists = p: ps: elem (version p) (map (x: version x) ps); + in + lib.lists.foldl' (acc: elem: if version-exists elem acc then acc else acc ++ [ elem ]) [ ]; + copy = nix: '' + cp -Rf ${nix.doc}/share/doc/nix/manual/* $out/manual/nix/${version nix} + ''; + # add upstream page redirects of the form ` `, excluding comments and empty lines + # TODO: once https://github.com/NixOS/nix/pull/9949 lands, bump the source and use: + # ${nix.doc}/share/doc/nix/manual/_redirects + # also remove the then unnecessary file from the root directory of the manual: + # rm $out/manual/nix/${version nix}/_redirects + redirects = nix: '' + sed '/^#/d;/^$/d;s#^\(.*\) \(.*\) #/manual/nix/${version nix}\1 /manual/nix/${version nix}\2 #g' ${nix.src}/doc/manual/_redirects >> $out/_redirects + ''; + shortlink = release: nix: '' + echo /nix/manual/${release} /nix/manual/${nix.version}/ 302 >> $out/_redirects + ''; + in + '' + mkdir -p $out + cp -R build/html/* $out/ + # NOTE: the comma in the shell expansion makes it also work for singleton lists + mkdir -p $out/manual/nix/{${concatStringsSep "," (mapAttrsToList (_: nix: version nix) nix-releases)},} + ${concatStringsSep "\n" (map copy (unique-version (attrValues nix-releases)))} + ${concatStringsSep "\n" (map redirects (unique-version (attrValues nix-releases)))} + ${concatStringsSep "\n" (mapAttrsToList shortlink nix-releases)} ''; - shortlink = release: version: '' - echo /manual/nix/${release} /manual/nix/${version}/ 302 >> $out/_redirects - ''; - versions = with pkgs.lib; lists.unique (attrsets.attrValues releases); - in - with pkgs.lib.attrsets; - with pkgs.lib.strings; - '' - mkdir -p $out - cp -R build/html/* $out/ - # NOTE: the comma in the shell expansion makes it also work for singleton lists - mkdir -p $out/manual/nix/{${concatStringsSep "," versions},} - ${concatStringsSep "\n" (map copy versions)} - ${concatStringsSep "\n" (map redirects versions)} - ${concatStringsSep "\n" (mapAttrsToList shortlink releases)} - ''; - }; + }; devmode = let diff --git a/nix/sources.json b/nix/sources.json index af08ddd..ca6c0bd 100644 --- a/nix/sources.json +++ b/nix/sources.json @@ -1,5 +1,5 @@ { - "nix_2-13": { + "nix-prev-stable": { "branch": "2.13-maintenance", "description": "Nix, the purely functional package manager", "homepage": "https://nixos.org/", @@ -11,7 +11,7 @@ "url": "https://github.com/nixos/nix/archive/25f2dfc6e41d8c30e7abc443a7b262e34e49253b.tar.gz", "url_template": "https://github.com///archive/.tar.gz" }, - "nix_2-18": { + "nix-rolling": { "branch": "2.18-maintenance", "description": "Nix, the purely functional package manager", "homepage": "https://nixos.org/", @@ -23,7 +23,7 @@ "url": "https://github.com/nixos/nix/archive/60eb80593f3a18aebc7672ad7007cb23c14db061.tar.gz", "url_template": "https://github.com///archive/.tar.gz" }, - "nix_2-19": { + "nix-latest": { "branch": "2.19-maintenance", "description": "Nix, the purely functional package manager", "homepage": "https://nixos.org/", @@ -35,7 +35,19 @@ "url": "https://github.com/nixos/nix/archive/dc09e6193bffcab37d3d43107eae9464395ab51d.tar.gz", "url_template": "https://github.com///archive/.tar.gz" }, - "nixpkgs": { + "nix-stable": { + "branch": "2.18-maintenance", + "description": "Nix, the purely functional package manager", + "homepage": "https://nixos.org/", + "owner": "nixos", + "repo": "nix", + "rev": "60eb80593f3a18aebc7672ad7007cb23c14db061", + "sha256": "0nyssab6skn9qd7mz4v0y3ycnhck7is6agm0i26l1anrgs90x37l", + "type": "tarball", + "url": "https://github.com/nixos/nix/archive/60eb80593f3a18aebc7672ad7007cb23c14db061.tar.gz", + "url_template": "https://github.com///archive/.tar.gz" + }, + "nixpkgs-prev-stable": { "branch": "nixos-23.05", "description": "Nix Packages collection & NixOS", "homepage": "", @@ -47,6 +59,30 @@ "url": "https://github.com/NixOS/nixpkgs/archive/898cb2064b6e98b8c5499f37e81adbdf2925f7c5.tar.gz", "url_template": "https://github.com///archive/.tar.gz" }, + "nixpkgs-rolling": { + "branch": "nixpkgs-unstable", + "description": "Nix Packages collection & NixOS", + "homepage": "", + "owner": "nixos", + "repo": "nixpkgs", + "rev": "8cc79aa39bbc6eaedaf286ae655b224c71e02907", + "sha256": "08yj32spm74bqnwq7wyaxzqjw3dc67bb3myx1baix506as54jr3y", + "type": "tarball", + "url": "https://github.com/nixos/nixpkgs/archive/8cc79aa39bbc6eaedaf286ae655b224c71e02907.tar.gz", + "url_template": "https://github.com///archive/.tar.gz" + }, + "nixpkgs-stable": { + "branch": "nixos-23.11", + "description": "Nix Packages collection & NixOS", + "homepage": "", + "owner": "nixos", + "repo": "nixpkgs", + "rev": "9f2ee8c91ac42da3ae6c6a1d21555f283458247e", + "sha256": "0imgfxzq7d7l6fcgnzzjvv6ch560svcm8s8bx8vqyvf60w24ma1d", + "type": "tarball", + "url": "https://github.com/nixos/nixpkgs/archive/9f2ee8c91ac42da3ae6c6a1d21555f283458247e.tar.gz", + "url_template": "https://github.com///archive/.tar.gz" + }, "poetry2nix": { "branch": "master", "description": "Convert poetry projects to nix automagically [maintainer=@adisbladis] ", diff --git a/source/reference/nix-manual.md b/source/reference/nix-manual.md index 7e67a08..e4038cd 100644 --- a/source/reference/nix-manual.md +++ b/source/reference/nix-manual.md @@ -1,35 +1,41 @@ (nix-manual)= # Nix reference manual + + ```{toctree} :hidden: Nix pre-release (development) -Nix 2.19 (latest) -Nix 2.18 (rolling) -Nix 2.18 (stable 23.11) -Nix 2.13 (stable 23.05) +Nix @nix-latest@ (latest) +Nix @nix-rolling@ (in Nixpkgs rolling) +Nix @nix-stable@ (in Nixpkgs @nixpkgs-stable@) +Nix @nix-prev-stable@ (in Nixpkgs @nixpkgs-prev-stable@) ``` - [Nix pre-release](https://hydra.nixos.org/job/nix/master/build.x86_64-linux/latest/download) - Reference documentation for the latest build from the `master` branch of the [Nix repository](https://github.com/NixOS/nix) + Latest build from the `master` branch of the [Nix repository](https://github.com/NixOS/nix) -- [Nix 2.19](https://nix.dev/manual/nix/2.19/) +- [Nix @nix-latest@](https://nix.dev/manual/nix/latest/) - Reference documentation for the latest Nix release + Latest Nix release -- [Nix 2.18](https://nix.dev/manual/nix/2.18/) +- [Nix @nix-rolling@](https://nix.dev/manual/nix/rolling/) - Reference documentation for the Nix version shipped with the {term}`Nixpkgs` and {term}`NixOS` rolling release + Shipped with the {term}`Nixpkgs` and {term}`NixOS` rolling release -- [Nix 2.18](https://nix.dev/manual/nix/2.18/) +- [Nix @nix-stable@](https://nix.dev/manual/nix/stable/) - Reference documentation for the Nix version shipped with the current {term}`Nixpkgs` and {term}`NixOS` stable release + Shipped with the current {term}`Nixpkgs` and {term}`NixOS` @nixpkgs-stable@ stable release -- [Nix 2.13](https://nix.dev/manual/nix/2.13/) +- [Nix @nix-prev-stable@](https://nix.dev/manual/nix/prev-stable/) - Reference documentation for the Nix version shipped with the previous {term}`Nixpkgs` and {term}`NixOS` stable release + Shipped with the previous {term}`Nixpkgs` and {term}`NixOS` @nixpkgs-prev-stable@ stable release :::{tip} More information on Nixpkgs and NixOS releases: [](channel-branches)