diff options
| author | John Ericson <John.Ericson@Obsidian.Systems> | 2022-03-10 15:48:14 +0000 |
|---|---|---|
| committer | John Ericson <John.Ericson@Obsidian.Systems> | 2022-03-10 15:48:14 +0000 |
| commit | 8ba089597fa19bfd49ba5f22a5e821740ca4eb5d (patch) | |
| tree | b4f2299b9c973ef7636f8ce1bab0299dee4cc389 /doc/manual | |
| parent | 13b6b645897fd2edaa0f09fa48d6fe8dd6287b55 (diff) | |
| parent | 4d98143914120d0163f5c50f30ce8a5289433f8f (diff) | |
Merge remote-tracking branch 'upstream/master' into path-info
Diffstat (limited to 'doc/manual')
41 files changed, 432 insertions, 167 deletions
diff --git a/doc/manual/generate-builtins.nix b/doc/manual/generate-builtins.nix index 92c7b1a31..6c8b88da2 100644 --- a/doc/manual/generate-builtins.nix +++ b/doc/manual/generate-builtins.nix @@ -6,9 +6,9 @@ builtins: concatStrings (map (name: let builtin = builtins.${name}; in - "<dt><code>${name} " + "<dt id=\"builtins-${name}\"><a href=\"#builtins-${name}\"><code>${name} " + concatStringsSep " " (map (s: "<var>${s}</var>") builtin.args) - + "</code></dt>" + + "</code></a></dt>" + "<dd>\n\n" + builtin.doc + "\n\n</dd>" diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix index 4fc9abea1..244cfa0c2 100644 --- a/doc/manual/generate-manpage.nix +++ b/doc/manual/generate-manpage.nix @@ -1,4 +1,4 @@ -command: +{ command, renderLinks ? false }: with builtins; with import ./utils.nix; @@ -20,7 +20,11 @@ let categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues def.commands))); listCommands = cmds: concatStrings (map (name: - "* [`${command} ${name}`](./${appendName filename name}.md) - ${cmds.${name}.description}\n") + "* " + + (if renderLinks + then "[`${command} ${name}`](./${appendName filename name}.md)" + else "`${command} ${name}`") + + " - ${cmds.${name}.description}\n") (attrNames cmds)); in "where *subcommand* is one of the following:\n\n" diff --git a/doc/manual/generate-options.nix b/doc/manual/generate-options.nix index 3c31a4eec..84d90beb6 100644 --- a/doc/manual/generate-options.nix +++ b/doc/manual/generate-options.nix @@ -8,17 +8,19 @@ concatStrings (map let option = options.${name}; in " - `${name}` \n\n" + concatStrings (map (s: " ${s}\n") (splitLines option.description)) + "\n\n" - + " **Default:** " + ( - if option.value == "" || option.value == [] - then "*empty*" - else if isBool option.value - then (if option.value then "`true`" else "`false`") - else - # n.b. a StringMap value type is specified as a string, but - # this shows the value type. The empty stringmap is "null" in - # JSON, but that converts to "{ }" here. - (if isAttrs option.value then "`\"\"`" - else "`" + toString option.value + "`")) + "\n\n" + + (if option.documentDefault + then " **Default:** " + ( + if option.value == "" || option.value == [] + then "*empty*" + else if isBool option.value + then (if option.value then "`true`" else "`false`") + else + # n.b. a StringMap value type is specified as a string, but + # this shows the value type. The empty stringmap is "null" in + # JSON, but that converts to "{ }" here. + (if isAttrs option.value then "`\"\"`" + else "`" + toString option.value + "`")) + "\n\n" + else " **Default:** *machine-specific*\n") + (if option.aliases != [] then " **Deprecated alias:** " + (concatStringsSep ", " (map (s: "`${s}`") option.aliases)) + "\n\n" else "") diff --git a/doc/manual/local.mk b/doc/manual/local.mk index a8c52f841..c1ce8aaeb 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -12,11 +12,13 @@ man-pages := $(foreach n, \ clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8 # Provide a dummy environment for nix, so that it will not access files outside the macOS sandbox. +# Set cores to 0 because otherwise nix show-config resolves the cores based on the current machine dummy-env = env -i \ HOME=/dummy \ NIX_CONF_DIR=/dummy \ NIX_SSL_CERT_FILE=/dummy/no-ca-bundle.crt \ - NIX_STATE_DIR=/dummy + NIX_STATE_DIR=/dummy \ + NIX_CONFIG='cores = 0' nix-eval = $(dummy-env) $(bindir)/nix eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw @@ -44,7 +46,7 @@ $(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/command-ref/new-cli $(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/generate-manpage.nix $(bindir)/nix @rm -rf $@ - $(trace-gen) $(nix-eval) --write-to $@ --expr 'import doc/manual/generate-manpage.nix (builtins.readFile $<)' + $(trace-gen) $(nix-eval) --write-to $@ --expr 'import doc/manual/generate-manpage.nix { command = builtins.readFile $<; renderLinks = true; }' $(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.nix $(d)/src/command-ref/conf-file-prefix.md $(bindir)/nix @cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp @@ -70,6 +72,7 @@ $(d)/builtins.json: $(bindir)/nix @mv $@.tmp $@ # Generate the HTML manual. +html: $(docdir)/manual/index.html install: $(docdir)/manual/index.html # Generate 'nix' manpages. diff --git a/doc/manual/src/SUMMARY.md.in b/doc/manual/src/SUMMARY.md.in index df9209c7d..f0f9457d2 100644 --- a/doc/manual/src/SUMMARY.md.in +++ b/doc/manual/src/SUMMARY.md.in @@ -9,6 +9,7 @@ - [Prerequisites](installation/prerequisites-source.md) - [Obtaining a Source Distribution](installation/obtaining-source.md) - [Building Nix from Source](installation/building-source.md) + - [Using Nix within Docker](installation/installing-docker.md) - [Security](installation/nix-security.md) - [Single-User Mode](installation/single-user.md) - [Multi-User Mode](installation/multi-user.md) @@ -70,7 +71,11 @@ - [Hacking](contributing/hacking.md) - [CLI guideline](contributing/cli-guideline.md) - [Release Notes](release-notes/release-notes.md) - - [Release 2.4 (2021-XX-XX)](release-notes/rl-2.4.md) + - [Release X.Y (202?-??-??)](release-notes/rl-next.md) + - [Release 2.7 (2022-03-07)](release-notes/rl-2.7.md) + - [Release 2.6 (2022-01-24)](release-notes/rl-2.6.md) + - [Release 2.5 (2021-12-13)](release-notes/rl-2.5.md) + - [Release 2.4 (2021-11-01)](release-notes/rl-2.4.md) - [Release 2.3 (2019-09-04)](release-notes/rl-2.3.md) - [Release 2.2 (2019-01-11)](release-notes/rl-2.2.md) - [Release 2.1 (2018-09-02)](release-notes/rl-2.1.md) diff --git a/doc/manual/src/advanced-topics/distributed-builds.md b/doc/manual/src/advanced-topics/distributed-builds.md index 580b36736..c4c60db15 100644 --- a/doc/manual/src/advanced-topics/distributed-builds.md +++ b/doc/manual/src/advanced-topics/distributed-builds.md @@ -53,8 +53,8 @@ example, the following command allows you to build a derivation for $ uname Linux -$ nix build \ - '(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \ +$ nix build --impure \ + --expr '(with import <nixpkgs> { system = "x86_64-darwin"; }; runCommand "foo" {} "uname > $out")' \ --builders 'ssh://mac x86_64-darwin' [1/0/1 built, 0.0 MiB DL] building foo on ssh://mac diff --git a/doc/manual/src/command-ref/conf-file-prefix.md b/doc/manual/src/command-ref/conf-file-prefix.md index 3140170ab..44b7ba86d 100644 --- a/doc/manual/src/command-ref/conf-file-prefix.md +++ b/doc/manual/src/command-ref/conf-file-prefix.md @@ -16,8 +16,9 @@ By default Nix reads settings from the following places: will be loaded in reverse order. Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` - and `XDG_CONFIG_HOME`. If these are unset, it will look in - `$HOME/.config/nix.conf`. + and `XDG_CONFIG_HOME`. If unset, `XDG_CONFIG_DIRS` defaults to + `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` + as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html). - If `NIX_CONFIG` is set, its contents is treated as the contents of a configuration file. diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md index 9138fa05a..8d6abaf52 100644 --- a/doc/manual/src/command-ref/nix-env.md +++ b/doc/manual/src/command-ref/nix-env.md @@ -238,7 +238,16 @@ a number of possible ways: ## Examples -To install a specific version of `gcc` from the active Nix expression: +To install a package using a specific attribute path from the active Nix expression: + +```console +$ nix-env -iA gcc40mips +installing `gcc-4.0.2' +$ nix-env -iA xorg.xorgserver +installing `xorg-server-1.2.0' +``` + +To install a specific version of `gcc` using the derivation name: ```console $ nix-env --install gcc-3.3.2 @@ -246,6 +255,9 @@ installing `gcc-3.3.2' uninstalling `gcc-3.1' ``` +Using attribute path for selecting a package is preferred, +as it is much faster and there will not be multiple matches. + Note the previously installed version is removed, since `--preserve-installed` was not specified. @@ -256,13 +268,6 @@ $ nix-env --install gcc installing `gcc-3.3.2' ``` -To install using a specific attribute: - -```console -$ nix-env -i -A gcc40mips -$ nix-env -i -A xorg.xorgserver -``` - To install all derivations in the Nix expression `foo.nix`: ```console @@ -374,22 +379,29 @@ For the other flags, see `--install`. ## Examples ```console -$ nix-env --upgrade gcc +$ nix-env --upgrade -A nixpkgs.gcc upgrading `gcc-3.3.1' to `gcc-3.4' ``` +When there are no updates available, nothing will happen: + ```console -$ nix-env -u gcc-3.3.2 --always (switch to a specific version) -upgrading `gcc-3.4' to `gcc-3.3.2' +$ nix-env --upgrade -A nixpkgs.pan ``` +Using `-A` is preferred when possible, as it is faster and unambiguous but +it is also possible to upgrade to a specific version by matching the derivation name: + ```console -$ nix-env --upgrade pan -(no upgrades available, so nothing happens) +$ nix-env -u gcc-3.3.2 --always +upgrading `gcc-3.4' to `gcc-3.3.2' ``` +To try to upgrade everything +(matching packages based on the part of the derivation name without version): + ```console -$ nix-env -u (try to upgrade everything) +$ nix-env -u upgrading `hello-2.1.2' to `hello-2.1.3' upgrading `mozilla-1.2' to `mozilla-1.4' ``` @@ -401,7 +413,7 @@ of a derivation `x` by looking at their respective `name` attributes. The names (e.g., `gcc-3.3.1` are split into two parts: the package name (`gcc`), and the version (`3.3.1`). The version part starts after the first dash not followed by a letter. `x` is considered an upgrade of `y` -if their package names match, and the version of `y` is higher that that +if their package names match, and the version of `y` is higher than that of `x`. The versions are compared by splitting them into contiguous components diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md index 72f6730f1..a2b6d8a8e 100644 --- a/doc/manual/src/command-ref/nix-shell.md +++ b/doc/manual/src/command-ref/nix-shell.md @@ -11,8 +11,8 @@ [`--command` *cmd*] [`--run` *cmd*] [`--exclude` *regexp*] - [--pure] - [--keep *name*] + [`--pure`] + [`--keep` *name*] {{`--packages` | `-p`} {*packages* | *expressions*} … | [*path*]} # Description @@ -101,7 +101,8 @@ The following common options are supported: - `NIX_BUILD_SHELL`\ Shell used to start the interactive environment. Defaults to the - `bash` found in `PATH`. + `bash` found in `<nixpkgs>`, falling back to the `bash` found in + `PATH` if not found. # Examples @@ -110,13 +111,19 @@ shell in which to build it: ```console $ nix-shell '<nixpkgs>' -A pan -[nix-shell]$ unpackPhase +[nix-shell]$ eval ${unpackPhase:-unpackPhase} [nix-shell]$ cd pan-* -[nix-shell]$ configurePhase -[nix-shell]$ buildPhase +[nix-shell]$ eval ${configurePhase:-configurePhase} +[nix-shell]$ eval ${buildPhase:-buildPhase} [nix-shell]$ ./pan/gui/pan ``` +The reason we use form `eval ${configurePhase:-configurePhase}` here is because +those packages that override these phases do so by exporting the overridden +values in the environment variable of the same name. +Here bash is being told to either evaluate the contents of 'configurePhase', +if it exists as a variable, otherwise evaluate the configurePhase function. + To clear the environment first, and do some additional automatic initialisation of the interactive shell: diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md index 7a131dc02..7db9f0c1c 100644 --- a/doc/manual/src/command-ref/nix-store.md +++ b/doc/manual/src/command-ref/nix-store.md @@ -125,7 +125,7 @@ Special exit codes: - `104`\ Not deterministic, the build succeeded in check mode but the - resulting output is not binary reproducable. + resulting output is not binary reproducible. With the `--keep-going` flag it's possible for multiple failures to occur, in this case the 1xx status codes are or combined using binary @@ -321,8 +321,8 @@ symlink. This query has one option: - `--include-outputs` - Also include the output path of store derivations, and their - closures. + Also include the existing output paths of store derivations, + and their closures. This query can be used to implement various kinds of deployment. A *source deployment* is obtained by distributing the closure of a diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md index 47862bc09..7ee1a26bc 100644 --- a/doc/manual/src/command-ref/opt-common.md +++ b/doc/manual/src/command-ref/opt-common.md @@ -162,11 +162,11 @@ Most Nix commands accept the following command-line options: }: ... ``` - So if you call this Nix expression (e.g., when you do `nix-env -i + So if you call this Nix expression (e.g., when you do `nix-env -iA pkgname`), the function will be called automatically using the value [`builtins.currentSystem`](../expressions/builtins.md) for the `system` argument. You can override this using `--arg`, e.g., - `nix-env -i pkgname --arg system \"i686-freebsd\"`. (Note that + `nix-env -iA pkgname --arg system \"i686-freebsd\"`. (Note that since the argument is a Nix string literal, you have to escape the quotes.) diff --git a/doc/manual/src/contributing/cli-guideline.md b/doc/manual/src/contributing/cli-guideline.md index 0132867c8..01a1b1e73 100644 --- a/doc/manual/src/contributing/cli-guideline.md +++ b/doc/manual/src/contributing/cli-guideline.md @@ -3,7 +3,7 @@ ## Goals Purpose of this document is to provide a clear direction to **help design -delightful command line** experience. This document contain guidelines to +delightful command line** experience. This document contains guidelines to follow to ensure a consistent and approachable user experience. ## Overview @@ -103,7 +103,7 @@ impacted the most by bad user experience. # Help is essential Help should be built into your command line so that new users can gradually -discover new features when they need them. +discover new features when they need them. ## Looking for help @@ -115,7 +115,7 @@ The rules are: - Help is shown by using `--help` or `help` command (eg `nix` `--``help` or `nix help`). -- For non-COMMANDs (eg. `nix` `--``help` and `nix store` `--``help`) we **show +- For non-COMMANDs (eg. `nix` `--``help` and `nix store` `--``help`) we **show a summary** of most common use cases. Summary is presented on the STDOUT without any use of PAGER. - For COMMANDs (eg. `nix init` `--``help` or `nix help init`) we display the @@ -176,7 +176,7 @@ $ nix init --template=template#pyton ------------------------------------------------------------------------ Initializing Nix project at `/path/to/here`. Select a template for you new project: - |> template#pyton + |> template#python template#python-pip template#python-poetry ``` @@ -230,17 +230,17 @@ Now **Learn** part of the output is where you educate users. You should only show it when you know that a build will take some time and not annoy users of the builds that take only few seconds. -Every feature like this should go though a intensive review and testing to -collect as much a feedback as possible and to fine tune every little detail. If +Every feature like this should go through an intensive review and testing to +collect as much feedback as possible and to fine tune every little detail. If done right this can be an awesome features beginners and advance users will love, but if not done perfectly it will annoy users and leave bad impression. # Input -Input to a command is provided via `ARGUMENTS` and `OPTIONS`. +Input to a command is provided via `ARGUMENTS` and `OPTIONS`. `ARGUMENTS` represent a required input for a function. When choosing to use -`ARGUMENT` over function please be aware of the downsides that come with it: +`ARGUMENTS` over `OPTIONS` please be aware of the downsides that come with it: - User will need to remember the order of `ARGUMENTS`. This is not a problem if there is only one `ARGUMENT`. @@ -253,7 +253,7 @@ developer consider the downsides and choose wisely. ## Naming the `OPTIONS` -Then only naming convention - apart from the ones mentioned in Naming the +The only naming convention - apart from the ones mentioned in Naming the `COMMANDS` section is how flags are named. Flags are a type of `OPTION` that represent an option that can be turned ON of @@ -271,12 +271,12 @@ to improve the discoverability of possible input. A new user will most likely not know which `ARGUMENTS` and `OPTIONS` are required or which values are possible for those options. -In cases, the user might not provide the input or they provide wrong input, -rather then show the error, prompt a user with an option to find and select +In case the user does not provide the input or they provide wrong input, +rather than show the error, prompt a user with an option to find and select correct input (see examples). Prompting is of course not required when TTY is not attached to STDIN. This -would mean that scripts wont need to handle prompt, but rather handle errors. +would mean that scripts won't need to handle prompt, but rather handle errors. A place to use prompt and provide user with interactive select @@ -300,9 +300,9 @@ going to happen. ```shell $ nix build --option substitutors https://cache.example.org ------------------------------------------------------------------------ - Warning! A security related question need to be answered. + Warning! A security related question needs to be answered. ------------------------------------------------------------------------ - The following substitutors will be used to in `my-project`: + The following substitutors will be used to in `my-project`: - https://cache.example.org Do you allow `my-project` to use above mentioned substitutors? @@ -311,14 +311,14 @@ $ nix build --option substitutors https://cache.example.org # Output -Terminal output can be quite limiting in many ways. Which should forces us to +Terminal output can be quite limiting in many ways. Which should force us to think about the experience even more. As with every design the output is a compromise between being terse and being verbose, between showing help to beginners and annoying advance users. For this it is important that we know what are the priorities. Nix command line should be first and foremost written with beginners in mind. -But users wont stay beginners for long and what was once useful might quickly +But users won't stay beginners for long and what was once useful might quickly become annoying. There is no golden rule that we can give in this guideline that would make it easier how to draw a line and find best compromise. @@ -342,7 +342,7 @@ also allowing them to redirect content to a file. For example: ```shell $ nix build > build.txt ------------------------------------------------------------------------ - Error! Atrribute `bin` missing at (1:94) from string. + Error! Attribute `bin` missing at (1:94) from string. ------------------------------------------------------------------------ 1| with import <nixpkgs> { }; (pkgs.runCommandCC or pkgs.runCommand) "shell" { buildInputs = [ (surge.bin) ]; } "" @@ -408,7 +408,7 @@ Above command clearly states that command successfully completed. And in case of `nix build`, which is a command that might take some time to complete, it is equally important to also show that a command started. -## Text alignment +## Text alignment Text alignment is the number one design element that will present all of the Nix commands as a family and not as separate tools glued together. @@ -419,7 +419,7 @@ The format we should follow is: $ nix COMMAND VERB_1 NOUN and other words VERB__1 NOUN and other words - |> Some details + |> Some details ``` Few rules that we can extract from above example: @@ -444,13 +444,13 @@ is not even notable, therefore relying on it wouldn’t make much sense. **The bright text is much better supported** across terminals and color schemes. Most of the time the difference is perceived as if the bright text -would be bold. +would be bold. ## Colors Humans are already conditioned by society to attach certain meaning to certain colors. While the meaning is not universal, a simple collection of colors is -used to represent basic emotions. +used to represent basic emotions. Colors that can be used in output @@ -508,7 +508,7 @@ can, with a few key strokes, be changed into and advance introspection tool. ### Progress -For longer running commands we should provide and overview of the progress. +For longer running commands we should provide and overview the progress. This is shown best in `nix build` example: ```shell @@ -553,9 +553,9 @@ going to happen. ```shell $ nix build --option substitutors https://cache.example.org ------------------------------------------------------------------------ - Warning! A security related question need to be answered. + Warning! A security related question needs to be answered. ------------------------------------------------------------------------ - The following substitutors will be used to in `my-project`: + The following substitutors will be used to in `my-project`: - https://cache.example.org Do you allow `my-project` to use above mentioned substitutors? @@ -566,7 +566,7 @@ $ nix build --option substitutors https://cache.example.org There are many ways that you can control verbosity. -Verbosity levels are: +Verbosity levels are: - `ERROR` (level 0) - `WARN` (level 1) @@ -586,4 +586,4 @@ There are also two shortcuts, `--debug` to run in `DEBUG` verbosity level and # Appendix 1: Commands naming exceptions -`nix init` and `nix repl` are well established +`nix init` and `nix repl` are well established diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 2a1e55e5b..90a8f1f94 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -35,6 +35,25 @@ variables are set up so that those dependencies can be found: $ nix-shell ``` +or if you have a flake-enabled nix: + +```console +$ nix develop +``` + +To get a shell with a different compilation environment (e.g. stdenv, +gccStdenv, clangStdenv, clang11Stdenv): + +```console +$ nix-shell -A devShells.x86_64-linux.clang11StdenvPackages +``` + +or if you have a flake-enabled nix: + +```console +$ nix develop .#clang11StdenvPackages +``` + To build Nix itself in this shell: ```console diff --git a/doc/manual/src/expressions/advanced-attributes.md b/doc/manual/src/expressions/advanced-attributes.md index 5b208df67..000595815 100644 --- a/doc/manual/src/expressions/advanced-attributes.md +++ b/doc/manual/src/expressions/advanced-attributes.md @@ -237,7 +237,7 @@ Derivations can declare some infrequently used optional attributes. - `preferLocalBuild`\ If this attribute is set to `true` and [distributed building is enabled](../advanced-topics/distributed-builds.md), then, if - possible, the derivaton will be built locally instead of forwarded + possible, the derivation will be built locally instead of forwarded to a remote machine. This is appropriate for trivial builders where the cost of doing a download or remote build would exceed the cost of building locally. diff --git a/doc/manual/src/expressions/builtins-prefix.md b/doc/manual/src/expressions/builtins-prefix.md index 87127de2a..c631a8453 100644 --- a/doc/manual/src/expressions/builtins-prefix.md +++ b/doc/manual/src/expressions/builtins-prefix.md @@ -12,5 +12,5 @@ For instance, `derivation` is also available as `builtins.derivation`. <dl> <dt><code>derivation <var>attrs</var></code>; <code>builtins.derivation <var>attrs</var></code></dt> - <dd><p><var>derivation</var> in described in + <dd><p><var>derivation</var> is described in <a href="derivations.md">its own section</a>.</p></dd> diff --git a/doc/manual/src/expressions/expression-syntax.md b/doc/manual/src/expressions/expression-syntax.md index 2a1306e32..6b93e692c 100644 --- a/doc/manual/src/expressions/expression-syntax.md +++ b/doc/manual/src/expressions/expression-syntax.md @@ -26,7 +26,7 @@ elements (referenced from the figure by number): called with three arguments: `stdenv`, `fetchurl`, and `perl`. They are needed to build Hello, but we don't know how to build them here; that's why they are function arguments. `stdenv` is a package that - is used by almost all Nix Packages packages; it provides a + is used by almost all Nix Packages; it provides a “standard” environment consisting of the things you would expect in a basic Unix environment: a C/C++ compiler (GCC, to be precise), the Bash shell, fundamental Unix tools such as `cp`, `grep`, `tar`, diff --git a/doc/manual/src/expressions/language-constructs.md b/doc/manual/src/expressions/language-constructs.md index cb0169239..1c01f2cc7 100644 --- a/doc/manual/src/expressions/language-constructs.md +++ b/doc/manual/src/expressions/language-constructs.md @@ -284,6 +284,10 @@ The points of interest are: function is called with the `localServer` argument set to `true` but the `db4` argument set to `null`, then the evaluation fails. + Note that `->` is the [logical + implication](https://en.wikipedia.org/wiki/Truth_table#Logical_implication) + Boolean operation. + 2. This is a more subtle condition: if Subversion is built with Apache (`httpServer`) support, then the Expat library (an XML library) used by Subversion should be same as the one used by Apache. This is diff --git a/doc/manual/src/expressions/language-operators.md b/doc/manual/src/expressions/language-operators.md index b7fd6f4c6..268b44f4c 100644 --- a/doc/manual/src/expressions/language-operators.md +++ b/doc/manual/src/expressions/language-operators.md @@ -17,12 +17,12 @@ order of precedence (from strongest to weakest binding). | String Concatenation | *string1* `+` *string2* | left | String concatenation. | 7 | | Not | `!` *e* | none | Boolean negation. | 8 | | Update | *e1* `//` *e2* | right | Return a set consisting of the attributes in *e1* and *e2* (with the latter taking precedence over the former in case of equally named attributes). | 9 | -| Less Than | *e1* `<` *e2*, | none | Arithmetic comparison. | 10 | -| Less Than or Equal To | *e1* `<=` *e2* | none | Arithmetic comparison. | 10 | -| Greater Than | *e1* `>` *e2* | none | Arithmetic comparison. | 10 | -| Greater Than or Equal To | *e1* `>=` *e2* | none | Arithmetic comparison. | 10 | +| Less Than | *e1* `<` *e2*, | none | Arithmetic/lexicographic comparison. | 10 | +| Less Than or Equal To | *e1* `<=` *e2* | none | Arithmetic/lexicographic comparison. | 10 | +| Greater Than | *e1* `>` *e2* | none | Arithmetic/lexicographic comparison. | 10 | +| Greater Than or Equal To | *e1* `>=` *e2* | none | Arithmetic/lexicographic comparison. | 10 | | Equality | *e1* `==` *e2* | none | Equality. | 11 | | Inequality | *e1* `!=` *e2* | none | Inequality. | 11 | | Logical AND | *e1* `&&` *e2* | left | Logical AND. | 12 | -| Logical OR | *e1* `\|\|` *e2* | left | Logical OR. | 13 | -| Logical Implication | *e1* `->` *e2* | none | Logical implication (equivalent to `!e1 \|\| e2`). | 14 | +| Logical OR | *e1* <code>||</code> *e2* | left | Logical OR. | 13 | +| Logical Implication | *e1* `->` *e2* | none | Logical implication (equivalent to <code>!e1 || e2</code>). | 14 | diff --git a/doc/manual/src/expressions/language-values.md b/doc/manual/src/expressions/language-values.md index 28fa23b58..75ae9f2eb 100644 --- a/doc/manual/src/expressions/language-values.md +++ b/doc/manual/src/expressions/language-values.md @@ -64,7 +64,7 @@ Nix has the following basic data types: the start of each line. To be precise, it strips from each line a number of spaces equal to the minimal indentation of the string as a whole (disregarding the indentation of empty lines). For instance, - the first and second line are indented two space, while the third + the first and second line are indented two spaces, while the third line is indented four spaces. Thus, two spaces are stripped from each line, so the resulting string is diff --git a/doc/manual/src/expressions/simple-building-testing.md b/doc/manual/src/expressions/simple-building-testing.md index 6f730a936..7f0d8f841 100644 --- a/doc/manual/src/expressions/simple-building-testing.md +++ b/doc/manual/src/expressions/simple-building-testing.md @@ -1,6 +1,6 @@ # Building and Testing -You can now try to build Hello. Of course, you could do `nix-env -i +You can now try to build Hello. Of course, you could do `nix-env -f . -iA hello`, but you may not want to install a possibly broken package just yet. The best way to test the package is by using the command `nix-build`, which builds a Nix expression and creates a symlink named diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index bb350d9de..71ff13275 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -47,7 +47,7 @@ the store object at `P` contains the path `Q` somewhere. The *references* of a store path are the set of store paths to which it has a reference. - + A derivation can reference other derivations and sources (but not output paths), whereas an output path only references other output paths. @@ -66,7 +66,7 @@ is necessary to deploy whole closures, since otherwise at runtime files could be missing. The command `nix-store -qR` prints out closures of store paths. - + As an example, if the store object at path `P` contains a reference to path `Q`, then `Q` is in the closure of `P`. Further, if `Q` references `R` then `R` is also in the closure of `P`. @@ -98,3 +98,7 @@ store. It can contain regular files, directories and symbolic links. NARs are generated and unpacked using `nix-store --dump` and `nix-store --restore`. + - `∅` \ + The empty set symbol. In the context of profile history, this denotes a package is not present in a particular version of the profile. + - `ε` \ + The epsilon symbol. In the context of a package, this means the version is empty. More precisely, the derivation does not have a version attribute. diff --git a/doc/manual/src/installation/building-source.md b/doc/manual/src/installation/building-source.md index d21a51a82..ed1efffd8 100644 --- a/doc/manual/src/installation/building-source.md +++ b/doc/manual/src/installation/building-source.md @@ -1,9 +1,9 @@ # Building Nix from Source -After unpacking or checking out the Nix sources, issue the following -commands: +After cloning Nix's Git repository, issue the following commands: ```console +$ ./bootstrap.sh $ ./configure options... $ make $ make install @@ -11,13 +11,6 @@ $ make install Nix requires GNU Make so you may need to invoke `gmake` instead. -When building from the Git repository, these should be preceded by the -command: - -```console -$ ./bootstrap.sh -``` - The installation path can be specified by passing the `--prefix=prefix` to `configure`. The default installation directory is `/usr/local`. You can change this to any location you like. You must have write permission diff --git a/doc/manual/src/installation/env-variables.md b/doc/manual/src/installation/env-variables.md index 4a49897e4..bb35c0e9f 100644 --- a/doc/manual/src/installation/env-variables.md +++ b/doc/manual/src/installation/env-variables.md @@ -40,7 +40,7 @@ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt > **Note** > > You must not add the export and then do the install, as the Nix -> installer will detect the presense of Nix configuration, and abort. +> installer will detect the presence of Nix configuration, and abort. ## `NIX_SSL_CERT_FILE` with macOS and the Nix daemon diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md index 96fa34635..4367654a2 100644 --- a/doc/manual/src/installation/installing-binary.md +++ b/doc/manual/src/installation/installing-binary.md @@ -119,6 +119,30 @@ this to run the installer, but it may help if you run into trouble: - update `/etc/synthetic.conf` to direct macOS to create a "synthetic" empty root directory to mount your volume - specify mount options for the volume in `/etc/fstab` + - `rw`: read-write + - `noauto`: prevent the system from auto-mounting the volume (so the + LaunchDaemon mentioned below can control mounting it, and to avoid + masking problems with that mounting service). + - `nobrowse`: prevent the Nix Store volume from showing up on your + desktop; also keeps Spotlight from spending resources to index + this volume + <!-- TODO: + - `suid`: honor setuid? surely not? ... + - `owners`: honor file ownership on the volume + + For now I'll avoid pretending to understand suid/owners more + than I do. There've been some vague reports of file-ownership + and permission issues, particularly in cloud/VM/headless setups. + My pet theory is that this has something to do with these setups + not having a token that gets delegated to initial/admin accounts + on macOS. See scripts/create-darwin-volume.sh for a little more. + + In any case, by Dec 4 2021, it _seems_ like some combination of + suid, owners, and calling diskutil enableOwnership have stopped + new reports from coming in. But I hesitate to celebrate because we + haven't really named and catalogued the behavior, understood what + we're fixing, and validated that all 3 components are essential. + --> - if you have FileVault enabled - generate an encryption password - put it in your system Keychain diff --git a/doc/manual/src/installation/installing-docker.md b/doc/manual/src/installation/installing-docker.md new file mode 100644 index 000000000..9d6d8f2d9 --- /dev/null +++ b/doc/manual/src/installation/installing-docker.md @@ -0,0 +1,59 @@ +# Using Nix within Docker + +To run the latest stable release of Nix with Docker run the following command: + +```console +$ docker run -ti nixos/nix +Unable to find image 'nixos/nix:latest' locally +latest: Pulling from nixos/nix +5843afab3874: Pull complete +b52bf13f109c: Pull complete +1e2415612aa3: Pull complete +Digest: sha256:27f6e7f60227e959ee7ece361f75d4844a40e1cc6878b6868fe30140420031ff +Status: Downloaded newer image for nixos/nix:latest +35ca4ada6e96:/# nix --version +nix (Nix) 2.3.12 +35ca4ada6e96:/# exit +``` + +# What is included in Nix's Docker image? + +The official Docker image is created using `pkgs.dockerTools.buildLayeredImage` +(and not with `Dockerfile` as it is usual with Docker images). You can still +base your custom Docker image on it as you would do with any other Docker +image. + +The Docker image is also not based on any other image and includes minimal set +of runtime dependencies that are required to use Nix: + + - pkgs.nix + - pkgs.bashInteractive + - pkgs.coreutils-full + - pkgs.gnutar + - pkgs.gzip + - pkgs.gnugrep + - pkgs.which + - pkgs.curl + - pkgs.less + - pkgs.wget + - pkgs.man + - pkgs.cacert.out + - pkgs.findutils + +# Docker image with the latest development version of Nix + +To get the latest image that was built by [Hydra](https://hydra.nixos.org) run +the following command: + +```console +$ curl -L https://hydra.nixos.org/job/nix/master/dockerImage.x86_64-linux/latest/download/1 | docker load +$ docker run -ti nix:2.5pre20211105 +``` + +You can also build a Docker image from source yourself: + +```console +$ nix build ./\#hydraJobs.dockerImage.x86_64-linux +$ docker load -i ./result/image.tar.gz +$ docker run -ti nix:2.5pre20211105 +``` diff --git a/doc/manual/src/installation/installing-source.md b/doc/manual/src/installation/installing-source.md index e52d38a03..09b4e4887 100644 --- a/doc/manual/src/installation/installing-source.md +++ b/doc/manual/src/installation/installing-source.md @@ -1,4 +1,4 @@ # Installing Nix from Source -If no binary package is available, you can download and compile a source -distribution. +If no binary package is available or if you want to hack on Nix, you +can build Nix from its Git repository. diff --git a/doc/manual/src/installation/obtaining-source.md b/doc/manual/src/installation/obtaining-source.md index 0a906e390..da05d243d 100644 --- a/doc/manual/src/installation/obtaining-source.md +++ b/doc/manual/src/installation/obtaining-source.md @@ -1,14 +1,9 @@ -# Obtaining a Source Distribution +# Obtaining the Source -The source tarball of the most recent stable release can be downloaded -from the [Nix homepage](http://nixos.org/nix/download.html). You can -also grab the [most recent development -release](http://hydra.nixos.org/job/nix/master/release/latest-finished#tabs-constituents). - -Alternatively, the most recent sources of Nix can be obtained from its -[Git repository](https://github.com/NixOS/nix). For example, the -following command will check out the latest revision into a directory -called `nix`: +The most recent sources of Nix can be obtained from its [Git +repository](https://github.com/NixOS/nix). For example, the following +command will check out the latest revision into a directory called +`nix`: ```console $ git clone https://github.com/NixOS/nix diff --git a/doc/manual/src/installation/prerequisites-source.md b/doc/manual/src/installation/prerequisites-source.md index 40cb79627..6f4eb3008 100644 --- a/doc/manual/src/installation/prerequisites-source.md +++ b/doc/manual/src/installation/prerequisites-source.md @@ -2,9 +2,8 @@ - GNU Autoconf (<https://www.gnu.org/software/autoconf/>) and the autoconf-archive macro collection - (<https://www.gnu.org/software/autoconf-archive/>). These are only - needed to run the bootstrap script, and are not necessary if your - source distribution came with a pre-built `./configure` script. + (<https://www.gnu.org/software/autoconf-archive/>). These are + needed to run the bootstrap script. - GNU Make. @@ -45,6 +44,11 @@ obtained from the its repository <https://github.com/troglobit/editline>. + - The `libsodium` library for verifying cryptographic signatures + of contents fetched from binary caches. + It can be obtained from the official web site + <https://libsodium.org>. + - Recent versions of Bison and Flex to build the parser. (This is because Nix needs GLR support in Bison and reentrancy support in Flex.) For Bison, you need version 2.6, which can be obtained from @@ -52,11 +56,18 @@ you need version 2.5.35, which is available on [SourceForge](http://lex.sourceforge.net/). Slightly older versions may also work, but ancient versions like the ubiquitous 2.5.4a - won't. Note that these are only required if you modify the parser or - when you are building from the Git repository. + won't. - The `libseccomp` is used to provide syscall filtering on Linux. This is an optional dependency and can be disabled passing a `--disable-seccomp-sandboxing` option to the `configure` script (Not recommended unless your system doesn't support `libseccomp`). To get the library, visit <https://github.com/seccomp/libseccomp>. + + - On 64-bit x86 machines only, `libcpuid` library + is used to determine which microarchitecture levels are supported + (e.g., as whether to have `x86_64-v2-linux` among additional system types). + The library is available from its homepage + <http://libcpuid.sourceforge.net>. + This is an optional dependency and can be disabled + by providing a `--disable-cpuid` to the `configure` script. diff --git a/doc/manual/src/installation/supported-platforms.md b/doc/manual/src/installation/supported-platforms.md index 8ef1f0e78..8ca3ce8d4 100644 --- a/doc/manual/src/installation/supported-platforms.md +++ b/doc/manual/src/installation/supported-platforms.md @@ -4,4 +4,4 @@ Nix is currently supported on the following platforms: - Linux (i686, x86\_64, aarch64). - - macOS (x86\_64). + - macOS (x86\_64, aarch64). diff --git a/doc/manual/src/introduction.md b/doc/manual/src/introduction.md index d68445c95..d87487a07 100644 --- a/doc/manual/src/introduction.md +++ b/doc/manual/src/introduction.md @@ -76,7 +76,7 @@ there after an upgrade. This means that you can _roll back_ to the old version: ```console -$ nix-env --upgrade some-packages +$ nix-env --upgrade -A nixpkgs.some-package $ nix-env --rollback ``` @@ -122,12 +122,12 @@ Nix expressions generally describe how to build a package from source, so an installation action like ```console -$ nix-env --install firefox +$ nix-env --install -A nixpkgs.firefox ``` _could_ cause quite a bit of build activity, as not only Firefox but also all its dependencies (all the way up to the C library and the -compiler) would have to built, at least if they are not already in the +compiler) would have to be built, at least if they are not already in the Nix store. This is a _source deployment model_. For most users, building from source is not very pleasant as it takes far too long. However, Nix can automatically skip building from source and instead diff --git a/doc/manual/src/package-management/basic-package-mgmt.md b/doc/manual/src/package-management/basic-package-mgmt.md index 9702a29eb..5f1d7a89c 100644 --- a/doc/manual/src/package-management/basic-package-mgmt.md +++ b/doc/manual/src/package-management/basic-package-mgmt.md @@ -24,7 +24,7 @@ collection; you could write your own Nix expressions based on Nixpkgs, or completely new ones.) You can manually download the latest version of Nixpkgs from -<http://nixos.org/nixpkgs/download.html>. However, it’s much more +<https://github.com/NixOS/nixpkgs>. However, it’s much more convenient to use the Nixpkgs [*channel*](channels.md), since it makes it easy to stay up to date with new versions of Nixpkgs. Nixpkgs is automatically added to your list of “subscribed” channels when you @@ -40,48 +40,52 @@ $ nix-channel --update > > On NixOS, you’re automatically subscribed to a NixOS channel > corresponding to your NixOS major release (e.g. -> <http://nixos.org/channels/nixos-14.12>). A NixOS channel is identical +> <http://nixos.org/channels/nixos-21.11>). A NixOS channel is identical > to the Nixpkgs channel, except that it contains only Linux binaries > and is updated only if a set of regression tests succeed. You can view the set of available packages in Nixpkgs: ```console -$ nix-env -qa -aterm-2.2 -bash-3.0 -binutils-2.15 -bison-1.875d -blackdown-1.4.2 -bzip2-1.0.2 +$ nix-env -qaP +nixpkgs.aterm aterm-2.2 +nixpkgs.bash bash-3.0 +nixpkgs.binutils binutils-2.15 +nixpkgs.bison bison-1.875d +nixpkgs.blackdown blackdown-1.4.2 +nixpkgs.bzip2 bzip2-1.0.2 … ``` -The flag `-q` specifies a query operation, and `-a` means that you want +The flag `-q` specifies a query operation, `-a` means that you want to show the “available” (i.e., installable) packages, as opposed to the -installed packages. If you downloaded Nixpkgs yourself, or if you -checked it out from GitHub, then you need to pass the path to your -Nixpkgs tree using the `-f` flag: +installed packages, and `-P` prints the attribute paths that can be used +to unambiguously select a package for installation (listed in the first column). +If you downloaded Nixpkgs yourself, or if you checked it out from GitHub, +then you need to pass the path to your Nixpkgs tree using the `-f` flag: ```console -$ nix-env -qaf /path/to/nixpkgs +$ nix-env -qaPf /path/to/nixpkgs +aterm aterm-2.2 +bash bash-3.0 +… ``` where */path/to/nixpkgs* is where you’ve unpacked or checked out Nixpkgs. -You can select specific packages by name: +You can filter the packages by name: ```console -$ nix-env -qa firefox -firefox-34.0.5 -firefox-with-plugins-34.0.5 +$ nix-env -qaP firefox +nixpkgs.firefox-esr firefox-91.3.0esr +nixpkgs.firefox firefox-94.0.1 ``` and using regular expressions: ```console -$ nix-env -qa 'firefox.*' +$ nix-env -qaP 'firefox.*' ``` It is also possible to see the *status* of available packages, i.e., @@ -89,11 +93,11 @@ whether they are installed into the user environment and/or present in the system: ```console -$ nix-env -qas +$ nix-env -qaPs … --PS bash-3.0 ---S binutils-2.15 -IPS bison-1.875d +-PS nixpkgs.bash bash-3.0 +--S nixpkgs.binutils binutils-2.15 +IPS nixpkgs.bison bison-1.875d … ``` @@ -106,13 +110,13 @@ which is Nix’s mechanism for doing binary deployment. It just means that Nix knows that it can fetch a pre-built package from somewhere (typically a network server) instead of building it locally. -You can install a package using `nix-env -i`. For instance, +You can install a package using `nix-env -iA`. For instance, ```console -$ nix-env -i subversion +$ nix-env -iA nixpkgs.subversion ``` -will install the package called `subversion` (which is, of course, the +will install the package called `subversion` from `nixpkgs` channel (which is, of course, the [Subversion version management system](http://subversion.tigris.org/)). > **Note** @@ -122,7 +126,7 @@ will install the package called `subversion` (which is, of course, the > binary cache <https://cache.nixos.org>; it contains binaries for most > packages in Nixpkgs. Only if no binary is available in the binary > cache, Nix will build the package from source. So if `nix-env -> -i subversion` results in Nix building stuff from source, then either +> -iA nixpkgs.subversion` results in Nix building stuff from source, then either > the package is not built for your platform by the Nixpkgs build > servers, or your version of Nixpkgs is too old or too new. For > instance, if you have a very recent checkout of Nixpkgs, then the @@ -133,7 +137,10 @@ will install the package called `subversion` (which is, of course, the > using a Git checkout of the Nixpkgs tree), you will get binaries for > most packages. -Naturally, packages can also be uninstalled: +Naturally, packages can also be uninstalled. Unlike when installing, you will +need to use the derivation name (though the version part can be omitted), +instead of the attribute path, as `nix-env` does not record which attribute +was used for installing: ```console $ nix-env -e subversion @@ -143,7 +150,7 @@ Upgrading to a new version is just as easy. If you have a new release of Nix Packages, you can do: ```console -$ nix-env -u subversion +$ nix-env -uA nixpkgs.subversion ``` This will *only* upgrade Subversion if there is a “newer” version in the diff --git a/doc/manual/src/package-management/binary-cache-substituter.md b/doc/manual/src/package-management/binary-cache-substituter.md index bdc5038fc..ef738794b 100644 --- a/doc/manual/src/package-management/binary-cache-substituter.md +++ b/doc/manual/src/package-management/binary-cache-substituter.md @@ -9,7 +9,7 @@ The daemon that handles binary cache requests via HTTP, `nix-serve`, is not part of the Nix distribution, but you can install it from Nixpkgs: ```console -$ nix-env -i nix-serve +$ nix-env -iA nixpkgs.nix-serve ``` You can then start the server, listening for HTTP connections on @@ -35,7 +35,7 @@ On the client side, you can tell Nix to use your binary cache using `--option extra-binary-caches`, e.g.: ```console -$ nix-env -i firefox --option extra-binary-caches http://avalon:8080/ +$ nix-env -iA nixpkgs.firefox --option extra-binary-caches http://avalon:8080/ ``` The option `extra-binary-caches` tells Nix to use this binary cache in diff --git a/doc/manual/src/package-management/garbage-collection.md b/doc/manual/src/package-management/garbage-collection.md index fecb30fd6..29a3b3101 100644 --- a/doc/manual/src/package-management/garbage-collection.md +++ b/doc/manual/src/package-management/garbage-collection.md @@ -44,7 +44,7 @@ collector as follows: $ nix-store --gc ``` -The behaviour of the gargage collector is affected by the +The behaviour of the garbage collector is affected by the `keep-derivations` (default: true) and `keep-outputs` (default: false) options in the Nix configuration file. The defaults will ensure that all derivations that are build-time dependencies of garbage collector roots diff --git a/doc/manual/src/package-management/profiles.md b/doc/manual/src/package-management/profiles.md index fbbfb7320..d1a2580d4 100644 --- a/doc/manual/src/package-management/profiles.md +++ b/doc/manual/src/package-management/profiles.md @@ -39,7 +39,7 @@ just Subversion 1.1.2 (arrows in the figure indicate symlinks). This would be what we would obtain if we had done ```console -$ nix-env -i subversion +$ nix-env -iA nixpkgs.subversion ``` on a set of Nix expressions that contained Subversion 1.1.2. @@ -54,7 +54,7 @@ environment is generated based on the current one. For instance, generation 43 was created from generation 42 when we did ```console -$ nix-env -i subversion firefox +$ nix-env -iA nixpkgs.subversion nixpkgs.firefox ``` on a set of Nix expressions that contained Firefox and a new version of @@ -127,7 +127,7 @@ All `nix-env` operations work on the profile pointed to by (abbreviation `-p`): ```console -$ nix-env -p /nix/var/nix/profiles/other-profile -i subversion +$ nix-env -p /nix/var/nix/profiles/other-profile -iA nixpkgs.subversion ``` This will *not* change the `~/.nix-profile` symlink. diff --git a/doc/manual/src/package-management/ssh-substituter.md b/doc/manual/src/package-management/ssh-substituter.md index 6e5e258bc..c59933f61 100644 --- a/doc/manual/src/package-management/ssh-substituter.md +++ b/doc/manual/src/package-management/ssh-substituter.md @@ -6,7 +6,7 @@ automatically fetching any store paths in Firefox’s closure if they are available on the server `avalon`: ```console -$ nix-env -i firefox --substituters ssh://alice@avalon +$ nix-env -iA nixpkgs.firefox --substituters ssh://alice@avalon ``` This works similar to the binary cache substituter that Nix usually diff --git a/doc/manual/src/quick-start.md b/doc/manual/src/quick-start.md index 71205923b..b54e73500 100644 --- a/doc/manual/src/quick-start.md +++ b/doc/manual/src/quick-start.md @@ -19,19 +19,19 @@ to subsequent chapters. channel: ```console - $ nix-env -qa - docbook-xml-4.3 - docbook-xml-4.5 - firefox-33.0.2 - hello-2.9 - libxslt-1.1.28 + $ nix-env -qaP + nixpkgs.docbook_xml_dtd_43 docbook-xml-4.3 + nixpkgs.docbook_xml_dtd_45 docbook-xml-4.5 + nixpkgs.firefox firefox-33.0.2 + nixpkgs.hello hello-2.9 + nixpkgs.libxslt libxslt-1.1.28 … ``` 1. Install some packages from the channel: ```console - $ nix-env -i hello + $ nix-env -iA nixpkgs.hello ``` This should download pre-built packages; it should not build them diff --git a/doc/manual/src/release-notes/rl-2.4.md b/doc/manual/src/release-notes/rl-2.4.md index def4a7b66..8b566fc7b 100644 --- a/doc/manual/src/release-notes/rl-2.4.md +++ b/doc/manual/src/release-notes/rl-2.4.md @@ -1,4 +1,4 @@ -# Release 2.4 (2021-10-XX) +# Release 2.4 (2021-11-01) This is the first release in more than two years and is the result of more than 2800 commits from 195 contributors since release 2.3. @@ -276,18 +276,62 @@ more than 2800 commits from 195 contributors since release 2.3. * Plugins can now register `nix` subcommands. +* The `--indirect` flag to `nix-store --add-root` has become a no-op. + `--add-root` will always generate indirect GC roots from now on. + ## Incompatible changes * The `nix` command is now marked as an experimental feature. This means that you need to add - > experimental-features = nix-command + ``` + experimental-features = nix-command + ``` to your `nix.conf` if you want to use it, or pass `--extra-experimental-features nix-command` on the command line. -* The old `nix run` has been renamed to `nix shell` (and there is a - new `nix run` that does something else, as described above). +* The `nix` command no longer has a syntax for referring to packages + in a channel. This means that the following no longer works: + + ```console + nix build nixpkgs.hello # Nix 2.3 + ``` + + Instead, you can either use the `#` syntax to select a package from + a flake, e.g. + + ```console + nix build nixpkgs#hello + ``` + + Or, if you want to use the `nixpkgs` channel in the `NIX_PATH` + environment variable: + + ```console + nix build -f '<nixpkgs>' hello + ``` + +* The old `nix run` has been renamed to `nix shell`, while there is a + new `nix run` that runs a default command. So instead of + + ```console + nix run nixpkgs.hello -c hello # Nix 2.3 + ``` + + you should use + + ```console + nix shell nixpkgs#hello -c hello + ``` + + or just + + ```console + nix run nixpkgs#hello + ``` + + if the command you want to run has the same name as the package. * It is now an error to modify the `plugin-files` setting via a command-line flag that appears after the first non-flag argument to @@ -354,6 +398,7 @@ dramforever, Dustin DeWeese, edef, Eelco Dolstra, +Ellie Hermaszewska, Emilio Karakey, Emily, Eric Culp, @@ -364,7 +409,7 @@ Federico Pellegrin, Finn Behrens, Florian Franzen, Félix Baylac-Jacqué, -Gabriel Gonzalez, +Gabriella Gonzalez, Geoff Reedy, Georges Dubus, Graham Christensen, @@ -387,7 +432,6 @@ Jaroslavas Pocepko, Jarrett Keifer, Jeremy Schlatter, Joachim Breitner, -Joe Hermaszewski, Joe Pea, John Ericson, Jonathan Ringer, diff --git a/doc/manual/src/release-notes/rl-2.5.md b/doc/manual/src/release-notes/rl-2.5.md new file mode 100644 index 000000000..dd6fd3b0f --- /dev/null +++ b/doc/manual/src/release-notes/rl-2.5.md @@ -0,0 +1,16 @@ +# Release 2.5 (2021-12-13) + +* The garbage collector no longer blocks new builds, so the message + `waiting for the big garbage collector lock...` is a thing of the + past. + +* Binary cache stores now have a setting `compression-level`. + +* `nix develop` now has a flag `--unpack` to run `unpackPhase`. + +* Lists can now be compared lexicographically using the `<` operator. + +* New built-in function: `builtins.groupBy`, with the same functionality as + Nixpkgs' `lib.groupBy`, but faster. + +* `nix repl` now has a `:log` command. diff --git a/doc/manual/src/release-notes/rl-2.6.md b/doc/manual/src/release-notes/rl-2.6.md new file mode 100644 index 000000000..280faead1 --- /dev/null +++ b/doc/manual/src/release-notes/rl-2.6.md @@ -0,0 +1,21 @@ +# Release 2.6 (2022-01-24) + +* The Nix CLI now searches for a `flake.nix` up until the root of the current + Git repository or a filesystem boundary rather than just in the current + directory. +* The TOML parser used by `builtins.fromTOML` has been replaced by [a + more compliant one](https://github.com/ToruNiina/toml11). +* Added `:st`/`:show-trace` commands to `nix repl`, which are used to + set or toggle display of error traces. +* New builtin function `builtins.zipAttrsWith` with the same + functionality as `lib.zipAttrsWith` from Nixpkgs, but much more + efficient. +* New command `nix store copy-log` to copy build logs from one store + to another. +* The `commit-lockfile-summary` option can be set to a non-empty + string to override the commit summary used when commiting an updated + lockfile. This may be used in conjunction with the `nixConfig` + attribute in `flake.nix` to better conform to repository + conventions. +* `docker run -ti nixos/nix:master` will place you in the Docker + container with the latest version of Nix from the `master` branch. diff --git a/doc/manual/src/release-notes/rl-2.7.md b/doc/manual/src/release-notes/rl-2.7.md new file mode 100644 index 000000000..dc92a9cde --- /dev/null +++ b/doc/manual/src/release-notes/rl-2.7.md @@ -0,0 +1,33 @@ +# Release X.Y (2022-03-07) + +* Nix will now make some helpful suggestions when you mistype + something on the command line. For instance, if you type `nix build + nixpkgs#thunderbrd`, it will suggest `thunderbird`. + +* A number of "default" flake output attributes have been + renamed. These are: + + * `defaultPackage.<system>` → `packages.<system>.default` + * `defaultApps.<system>` → `apps.<system>.default` + * `defaultTemplate` → `templates.default` + * `defaultBundler.<system>` → `bundlers.<system>.default` + * `overlay` → `overlays.default` + * `devShell.<system>` → `devShells.<system>.default` + + The old flake output attributes still work, but `nix flake check` + will warn about them. + +* Breaking API change: `nix bundle` now supports bundlers of the form + `bundler.<system>.<name>= derivation: another-derivation;`. This + supports additional functionality to inspect evaluation information + during bundling. A new + [repository](https://github.com/NixOS/bundlers) has various bundlers + implemented. + +* `nix store ping` now reports the version of the remote Nix daemon. + +* `nix flake {init,new}` now display information about which files have been + created. + +* Templates can now define a `welcomeText` attribute, which is printed out by + `nix flake {init,new} --template <template>`. diff --git a/doc/manual/src/release-notes/rl-next.md b/doc/manual/src/release-notes/rl-next.md new file mode 100644 index 000000000..c869b5e2f --- /dev/null +++ b/doc/manual/src/release-notes/rl-next.md @@ -0,0 +1 @@ +# Release X.Y (202?-??-??) |