diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/manual/custom.css | 4 | ||||
| -rw-r--r-- | doc/manual/local.mk | 6 | ||||
| -rw-r--r-- | doc/manual/src/command-ref/env-common.md | 13 | ||||
| -rw-r--r-- | doc/manual/src/contributing/hacking.md | 158 | ||||
| -rw-r--r-- | doc/manual/src/glossary.md | 7 | ||||
| -rw-r--r-- | doc/manual/src/installation/env-variables.md | 4 | ||||
| -rw-r--r-- | doc/manual/src/installation/installing-binary.md | 8 | ||||
| -rw-r--r-- | doc/manual/src/language/advanced-attributes.md | 25 | ||||
| -rw-r--r-- | doc/manual/src/language/index.md | 2 | ||||
| -rw-r--r-- | doc/manual/src/language/operators.md | 6 | ||||
| -rw-r--r-- | doc/manual/src/quick-start.md | 2 |
11 files changed, 188 insertions, 47 deletions
diff --git a/doc/manual/custom.css b/doc/manual/custom.css index 69d48d4a7..b90f5423f 100644 --- a/doc/manual/custom.css +++ b/doc/manual/custom.css @@ -5,3 +5,7 @@ h1:not(:first-of-type) { h2 { margin-top: 1em; } + +.hljs-meta { + user-select: none; +} diff --git a/doc/manual/local.mk b/doc/manual/local.mk index 190f0258a..f43510b6d 100644 --- a/doc/manual/local.mk +++ b/doc/manual/local.mk @@ -51,13 +51,13 @@ $(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 $@.tmp --expr 'import doc/manual/generate-manpage.nix { toplevel = builtins.readFile $<; }' - # @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable + @# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable $(trace-gen) sed -i $@.tmp/*.md -e 's^@docroot@^../..^g' @mv $@.tmp $@ $(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 - # @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable + @# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-options.nix (builtins.fromJSON (builtins.readFile $<))' \ | sed -e 's^@docroot@^..^g'>> $@.tmp @mv $@.tmp $@ @@ -72,7 +72,7 @@ $(d)/conf-file.json: $(bindir)/nix $(d)/src/language/builtins.md: $(d)/builtins.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(bindir)/nix @cat doc/manual/src/language/builtins-prefix.md > $@.tmp - # @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable + @# @docroot@: https://nixos.org/manual/nix/unstable/contributing/hacking.html#docroot-variable $(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<))' \ | sed -e 's^@docroot@^..^g' >> $@.tmp @cat doc/manual/src/language/builtins-suffix.md >> $@.tmp diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md index bb85a6b07..c5d38db47 100644 --- a/doc/manual/src/command-ref/env-common.md +++ b/doc/manual/src/command-ref/env-common.md @@ -91,3 +91,16 @@ Most Nix commands interpret the following environment variables: variable sets the initial size of the heap in bytes. It defaults to 384 MiB. Setting it to a low value reduces memory consumption, but will increase runtime due to the overhead of garbage collection. + +## XDG Base Directory + +New Nix commands conform to the [XDG Base Directory Specification], and use the following environment variables to determine locations of various state and configuration files: + +- [`XDG_CONFIG_HOME`]{#env-XDG_CONFIG_HOME} (default `~/.config`) +- [`XDG_STATE_HOME`]{#env-XDG_STATE_HOME} (default `~/.local/state`) +- [`XDG_CACHE_HOME`]{#env-XDG_CACHE_HOME} (default `~/.cache`) + +Classic Nix commands can also be made to follow this standard using the [`use-xdg-base-directories`] configuration option. + +[XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +[`use-xdg-base-directories`]: ../command-ref/conf-file.md#conf-use-xdg-base-directories
\ No newline at end of file diff --git a/doc/manual/src/contributing/hacking.md b/doc/manual/src/contributing/hacking.md index 9dbafcc0a..3869c37a4 100644 --- a/doc/manual/src/contributing/hacking.md +++ b/doc/manual/src/contributing/hacking.md @@ -8,54 +8,82 @@ $ git clone https://github.com/NixOS/nix.git $ cd nix ``` -To build Nix for the current operating system/architecture use +The following instructions assume you already have some version of Nix installed locally, so that you can use it to set up the development environment. If you don't have it installed, follow the [installation instructions]. + +[installation instructions]: ../installation/installation.md + +## Nix with flakes + +This section assumes you are using Nix with [flakes] enabled. See the [next section](#classic-nix) for equivalent instructions which don't require flakes. + +[flakes]: ../command-ref/new-cli/nix3-flake.md#description + +To build all dependencies and start a shell in which all environment +variables are set up so that those dependencies can be found: ```console -$ nix-build +$ nix develop ``` -or if you have a flake-enabled nix: +This shell also adds `./outputs/bin/nix` to your `$PATH` so you can run `nix` immediately after building it. + +To get a shell with one of the other [supported compilation environments](#compilation-environments): ```console -$ nix build +$ nix develop .#native-clang11StdenvPackages ``` -This will build `defaultPackage` attribute defined in the `flake.nix` -file. To build for other platforms add one of the following suffixes to -it: aarch64-linux, i686-linux, x86\_64-darwin, x86\_64-linux. i.e. +> **Note** +> +> Use `ccacheStdenv` to drastically improve rebuild time. +> By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`. + +To build Nix itself in this shell: ```console -$ nix-build -A defaultPackage.x86_64-linux +[nix-shell]$ ./bootstrap.sh +[nix-shell]$ ./configure $configureFlags --prefix=$(pwd)/outputs/out +[nix-shell]$ make -j $NIX_BUILD_CORES ``` -To build all dependencies and start a shell in which all environment -variables are set up so that those dependencies can be found: +To install it in `$(pwd)/outputs` and test it: ```console -$ nix-shell +[nix-shell]$ make install +[nix-shell]$ make installcheck -j $NIX_BUILD_CORES +[nix-shell]$ nix --version +nix (Nix) 2.12 ``` -or if you have a flake-enabled nix: +To build a release version of Nix: ```console -$ nix develop +$ nix build ``` -To get a shell with a different compilation environment (e.g. stdenv, -gccStdenv, clangStdenv, clang11Stdenv, ccacheStdenv): +You can also build Nix for one of the [supported target platforms](#target-platforms). + +## Classic Nix + +This section is for Nix without [flakes]. + +To build all dependencies and start a shell in which all environment +variables are set up so that those dependencies can be found: ```console -$ nix-shell -A devShells.x86_64-linux.clang11StdenvPackages +$ nix-shell ``` -or if you have a flake-enabled nix: +To get a shell with one of the other [supported compilation environments](#compilation-environments): ```console -$ nix develop .#clang11StdenvPackages +$ nix-shell -A devShells.x86_64-linux.native-clang11StdenvPackages ``` -Note: you can use `ccacheStdenv` to drastically improve rebuild -time. By default, ccache keeps artifacts in `~/.cache/ccache/`. +> **Note** +> +> You can use `native-ccacheStdenvPackages` to drastically improve rebuild time. +> By default, [ccache](https://ccache.dev) keeps artifacts in `~/.cache/ccache/`. To build Nix itself in this shell: @@ -71,21 +99,99 @@ To install it in `$(pwd)/outputs` and test it: [nix-shell]$ make install [nix-shell]$ make installcheck -j $NIX_BUILD_CORES [nix-shell]$ ./outputs/out/bin/nix --version -nix (Nix) 3.0 +nix (Nix) 2.12 ``` -If you have a flakes-enabled Nix you can replace: +To build Nix for the current operating system and CPU architecture use ```console -$ nix-shell +$ nix-build +``` + +You can also build Nix for one of the [supported target platforms](#target-platforms). + +## Platforms + +As specified in [`flake.nix`], Nix can be built for various platforms: + +- `aarch64-linux` +- `i686-linux` +- `x86_64-darwin` +- `x86_64-linux` + +[`flake.nix`]: https://github.com/nixos/nix/blob/master/flake.nix + +In order to build Nix for a different platform than the one you're currently +on, you need to have some way for your system Nix to build code for that +platform. Common solutions include [remote builders] and [binfmt emulation] +(only supported on NixOS). + +[remote builders]: ../advanced-topics/distributed-builds.md +[binfmt emulation]: https://nixos.org/manual/nixos/stable/options.html#opt-boot.binfmt.emulatedSystems + +These solutions let Nix perform builds as if you're on the native platform, so +executing the build is as simple as + +```console +$ nix build .#packages.aarch64-linux.default ``` -by: +for flake-enabled Nix, or ```console -$ nix develop +$ nix-build -A packages.aarch64-linux.default +``` + +for classic Nix. + +You can use any of the other supported platforms in place of `aarch64-linux`. + +Cross-compiled builds are available for ARMv6 and ARMv7, and Nix on unsupported platforms can be bootstrapped by adding more `crossSystems` in `flake.nix`. + +## Compilation environments + +Nix can be compiled using multiple environments: + +- `stdenv`: default; +- `gccStdenv`: force the use of `gcc` compiler; +- `clangStdenv`: force the use of `clang` compiler; +- `ccacheStdenv`: enable [ccache], a compiler cache to speed up compilation. + +To build with one of those environments, you can use + +```console +$ nix build .#nix-ccacheStdenv ``` +for flake-enabled Nix, or + +```console +$ nix-build -A nix-ccacheStdenv +``` + +for classic Nix. + +You can use any of the other supported environments in place of `nix-ccacheStdenv`. + +## Editor integration + +The `clangd` LSP server is installed by default on the `clang`-based `devShell`s. +See [supported compilation environments](#compilation-environments) and instructions how to set up a shell [with flakes](#nix-with-flakes) or in [classic Nix](#classic-nix). + +To use the LSP with your editor, you first need to [set up `clangd`](https://clangd.llvm.org/installation#project-setup) by running: + +```console +make clean && bear -- make -j$NIX_BUILD_CORES install +``` + +Configure your editor to use the `clangd` from the shell, either by running it inside the development shell, or by using [nix-direnv](https://github.com/nix-community/nix-direnv) and [the appropriate editor plugin](https://github.com/direnv/direnv/wiki#editor-integration). + +> **Note** +> +> For some editors (e.g. Visual Studio Code), you may need to install a [special extension](https://open-vsx.org/extension/llvm-vs-code-extensions/vscode-clangd) for the editor to interact with `clangd`. +> Some other editors (e.g. Emacs, Vim) need a plugin to support LSP servers in general (e.g. [lsp-mode](https://github.com/emacs-lsp/lsp-mode) for Emacs and [vim-lsp](https://github.com/prabirshrestha/vim-lsp) for vim). +> Editor-specific setup is typically opinionated, so we will not cover it here in more detail. + ## Running tests ### Unit-tests @@ -219,7 +325,7 @@ After the CI run completes, you can check the output to extract the installer UR 5. To generate an install command, plug this `install_url` and your GitHub username into this template: ```console - sh <(curl -L <install_url>) --tarball-url-prefix https://<github-username>-nix-install-tests.cachix.org/serve + curl -L <install_url> | sh -s -- --tarball-url-prefix https://<github-username>-nix-install-tests.cachix.org/serve ``` <!-- #### Manually generating test installers diff --git a/doc/manual/src/glossary.md b/doc/manual/src/glossary.md index 6004df833..d0aff34e2 100644 --- a/doc/manual/src/glossary.md +++ b/doc/manual/src/glossary.md @@ -19,6 +19,13 @@ [store derivation]: #gloss-store-derivation + - [instantiate]{#gloss-instantiate}, instantiation\ + Translate a [derivation] into a [store derivation]. + + See [`nix-instantiate`](./command-ref/nix-instantiate.md). + + [instantiate]: #gloss-instantiate + - [realise]{#gloss-realise}, realisation\ Ensure a [store path] is [valid][validity]. diff --git a/doc/manual/src/installation/env-variables.md b/doc/manual/src/installation/env-variables.md index bb35c0e9f..fb8155a80 100644 --- a/doc/manual/src/installation/env-variables.md +++ b/doc/manual/src/installation/env-variables.md @@ -27,7 +27,7 @@ Set the environment variable and install Nix ```console $ export NIX_SSL_CERT_FILE=/etc/ssl/my-certificate-bundle.crt -$ sh <(curl -L https://nixos.org/nix/install) +$ curl -L https://nixos.org/nix/install | sh ``` In the shell profile and rc files (for example, `/etc/bashrc`, @@ -38,7 +38,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 presence of Nix configuration, and abort. diff --git a/doc/manual/src/installation/installing-binary.md b/doc/manual/src/installation/installing-binary.md index 53fdbe31a..e3fd962bd 100644 --- a/doc/manual/src/installation/installing-binary.md +++ b/doc/manual/src/installation/installing-binary.md @@ -3,7 +3,7 @@ The easiest way to install Nix is to run the following command: ```console -$ sh <(curl -L https://nixos.org/nix/install) +$ curl -L https://nixos.org/nix/install | sh ``` This will run the installer interactively (causing it to explain what @@ -27,7 +27,7 @@ you can authenticate with `sudo`. To explicitly select a single-user installation on your system: ```console -$ sh <(curl -L https://nixos.org/nix/install) --no-daemon +$ curl -L https://nixos.org/nix/install | sh -s -- --no-daemon ``` This will perform a single-user installation of Nix, meaning that `/nix` @@ -66,7 +66,7 @@ You can instruct the installer to perform a multi-user installation on your system: ```console -$ sh <(curl -L https://nixos.org/nix/install) --daemon +$ curl -L https://nixos.org/nix/install | sh -s -- --daemon ``` The multi-user installation of Nix will create build users between the @@ -287,7 +287,7 @@ These install scripts can be used the same as the main NixOS.org installation script: ```console -$ sh <(curl -L https://nixos.org/nix/install) +$ curl -L https://nixos.org/nix/install | sh ``` In the same directory of the install script are sha256 sums, and gpg diff --git a/doc/manual/src/language/advanced-attributes.md b/doc/manual/src/language/advanced-attributes.md index a164b3997..5a63236e5 100644 --- a/doc/manual/src/language/advanced-attributes.md +++ b/doc/manual/src/language/advanced-attributes.md @@ -260,7 +260,7 @@ Derivations can declare some infrequently used optional attributes. If the special attribute `__structuredAttrs` is set to `true`, the other derivation attributes are serialised in JSON format and made available to the builder via the file `.attrs.json` in the builder’s temporary - directory. This obviates the need for `passAsFile` since JSON files + directory. This obviates the need for [`passAsFile`](#adv-attr-passAsFile) since JSON files have no size restrictions, unlike process environments. It also makes it possible to tweak derivation settings in a structured way; see @@ -282,11 +282,13 @@ Derivations can declare some infrequently used optional attributes. [`disallowedReferences`](#adv-attr-disallowedReferences) and [`disallowedRequisites`](#adv-attr-disallowedRequisites), the following attributes are available: - - `maxSize` defines the maximum size of the output path. + - `maxSize` defines the maximum size of the resulting [store object](../glossary.md#gloss-store-object). - `maxClosureSize` defines the maximum size of the output's closure. - `ignoreSelfRefs` controls whether self-references should be considered when checking for allowed references/requisites. + Example: + ```nix __structuredAttrs = true; @@ -305,9 +307,20 @@ Derivations can declare some infrequently used optional attributes. ``` - [`unsafeDiscardReferences`]{#adv-attr-unsafeDiscardReferences}\ - When using [structured attributes](#adv-attr-structuredAttrs), the **experimental** - attribute `unsafeDiscardReferences` is a per-output boolean which, if set to `true`, - disables scanning the build output for runtime dependencies altogether. + > **Warning** + > This is an experimental feature. + > + > To enable it, add the following to [nix.conf](../command-ref/conf-file.md): + > + > ``` + > extra-experimental-features = discard-references + > ``` + + When using [structured attributes](#adv-attr-structuredAttrs), the + attribute `unsafeDiscardReferences` is an attribute set with a boolean value for each output name. + If set to `true`, it disables scanning the output for runtime dependencies. + + Example: ```nix __structuredAttrs = true; @@ -317,5 +330,3 @@ Derivations can declare some infrequently used optional attributes. This is useful, for example, when generating self-contained filesystem images with their own embedded Nix store: hashes found inside such an image refer to the embedded store and not to the host's Nix store. - - This is only allowed if the `discard-references` experimental feature is enabled. diff --git a/doc/manual/src/language/index.md b/doc/manual/src/language/index.md index 31300631c..3eabe1a02 100644 --- a/doc/manual/src/language/index.md +++ b/doc/manual/src/language/index.md @@ -91,7 +91,7 @@ This is an incomplete overview of language features, by example. <tr> <td> - `"hello ${ { a = "world" }.a }"` + `"hello ${ { a = "world"; }.a }"` `"1 2 ${toString 3}"` diff --git a/doc/manual/src/language/operators.md b/doc/manual/src/language/operators.md index 1f918bd4d..90b325597 100644 --- a/doc/manual/src/language/operators.md +++ b/doc/manual/src/language/operators.md @@ -24,7 +24,7 @@ | [Equality] | *expr* `==` *expr* | none | 11 | | Inequality | *expr* `!=` *expr* | none | 11 | | Logical conjunction (`AND`) | *bool* `&&` *bool* | left | 12 | -| Logical disjunction (`OR`) | *bool* `\|\|` *bool* | left | 13 | +| Logical disjunction (`OR`) | *bool* <code>\|\|</code> *bool* | left | 13 | | [Logical implication] | *bool* `->` *bool* | none | 14 | [string]: ./values.md#type-string @@ -116,7 +116,7 @@ The result is a string. [store path]: ../glossary.md#gloss-store-path [store]: ../glossary.md#gloss-store -[Path and string concatenation]: #path-and-string-concatenation +[String and path concatenation]: #string-and-path-concatenation ## Update @@ -133,7 +133,7 @@ If an attribute name is present in both, the attribute value from the latter is Comparison is -- [arithmetic] for [number]s +- [arithmetic] for [number]s - lexicographic for [string]s and [path]s - item-wise lexicographic for [list]s: elements at the same index in both lists are compared according to their type and skipped if they are equal. diff --git a/doc/manual/src/quick-start.md b/doc/manual/src/quick-start.md index e11549984..651134c25 100644 --- a/doc/manual/src/quick-start.md +++ b/doc/manual/src/quick-start.md @@ -7,7 +7,7 @@ to subsequent chapters. 1. Install Nix by running the following: ```console - $ bash <(curl -L https://nixos.org/nix/install) --daemon + $ curl -L https://nixos.org/nix/install | sh ``` The install script will use `sudo`, so make sure you have sufficient rights. |