diff options
Diffstat (limited to 'doc')
60 files changed, 878 insertions, 2341 deletions
diff --git a/doc/build-aux/pandoc-filters/link-unix-man-references.lua b/doc/build-aux/pandoc-filters/link-unix-man-references.lua index e437ac73a1cb..b81d4a0979e7 100644 --- a/doc/build-aux/pandoc-filters/link-unix-man-references.lua +++ b/doc/build-aux/pandoc-filters/link-unix-man-references.lua @@ -3,10 +3,31 @@ Turns a manpage reference into a link, when a mapping is defined below. ]] local man_urls = { - ["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html", ["nix.conf(5)"] = "https://nixos.org/manual/nix/stable/#sec-conf-file", - ["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html", + + ["journald.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/journald.conf.html", + ["logind.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/logind.conf.html", + ["networkd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/networkd.conf.html", + ["systemd.automount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.automount.html", + ["systemd.exec(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.exec.html", + ["systemd.link(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.link.html", + ["systemd.mount(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.mount.html", + ["systemd.netdev(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.netdev.html", + ["systemd.network(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.network.html", + ["systemd.nspawn(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.nspawn.html", + ["systemd.path(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.path.html", + ["systemd.resource-control(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html", + ["systemd.scope(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.scope.html", + ["systemd.service(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.service.html", + ["systemd.slice(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.slice.html", + ["systemd.socket(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.socket.html", ["systemd.timer(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.timer.html", + ["systemd.unit(5)"] = "https://www.freedesktop.org/software/systemd/man/systemd.unit.html", + ["timesyncd.conf(5)"] = "https://www.freedesktop.org/software/systemd/man/timesyncd.conf.html", + ["tmpfiles.d(5)"] = "https://www.freedesktop.org/software/systemd/man/tmpfiles.d.html", + ["systemd.time(7)"] = "https://www.freedesktop.org/software/systemd/man/systemd.time.html", + ["systemd-fstab-generator(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-fstab-generator.html", + ["systemd-networkd-wait-online.service(8)"] = "https://www.freedesktop.org/software/systemd/man/systemd-networkd-wait-online.service.html", } function Code(elem) diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md index 12d8a5d887fd..773eb3028ddb 100644 --- a/doc/builders/fetchers.chapter.md +++ b/doc/builders/fetchers.chapter.md @@ -14,7 +14,7 @@ For example, consider the following fetcher: ```nix fetchurl { url = "http://www.example.org/hello-1.0.tar.gz"; - sha256 = "0v6r3wwnsk5pdjr188nip3pjgn1jrn5pc5ajpcfy6had6b3v4dwm"; + hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww="; }; ``` @@ -23,17 +23,17 @@ A common mistake is to update a fetcher’s URL, or a version parameter, without ```nix fetchurl { url = "http://www.example.org/hello-1.1.tar.gz"; - sha256 = "0v6r3wwnsk5pdjr188nip3pjgn1jrn5pc5ajpcfy6had6b3v4dwm"; + hash = "sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww="; }; ``` **This will reuse the old contents**. -Remember to invalidate the hash argument, in this case by setting the `sha256` attribute to an empty string. +Remember to invalidate the hash argument, in this case by setting the `hash` attribute to an empty string. ```nix fetchurl { url = "http://www.example.org/hello-1.1.tar.gz"; - sha256 = ""; + hash = ""; }; ``` @@ -42,14 +42,14 @@ Use the resulting error message to determine the correct hash. ``` error: hash mismatch in fixed-output derivation '/path/to/my.drv': specified: sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA= - got: sha256-RApQUm78dswhBLC/rfU9y0u6pSAzHceIJqgmetRD24E= + got: sha256-lTeyxzJNQeMdu1IVdovNMtgn77jRIhSybLdMbTkf2Ww= ``` A similar problem arises while testing changes to a fetcher's implementation. If the output of the derivation already exists in the Nix store, test failures can go undetected. The [`invalidateFetcherByDrvHash`](#tester-invalidateFetcherByDrvHash) function helps prevent reusing cached derivations. ## `fetchurl` and `fetchzip` {#fetchurl} -Two basic fetchers are `fetchurl` and `fetchzip`. Both of these have two required arguments, a URL and a hash. The hash is typically `sha256`, although many more hash algorithms are supported. Nixpkgs contributors are currently recommended to use `sha256`. This hash will be used by Nix to identify your source. A typical usage of `fetchurl` is provided below. +Two basic fetchers are `fetchurl` and `fetchzip`. Both of these have two required arguments, a URL and a hash. The hash is typically `hash`, although many more hash algorithms are supported. Nixpkgs contributors are currently recommended to use `hash`. This hash will be used by Nix to identify your source. A typical usage of `fetchurl` is provided below. ```nix { stdenv, fetchurl }: @@ -58,7 +58,7 @@ stdenv.mkDerivation { name = "hello"; src = fetchurl { url = "http://www.example.org/hello.tar.gz"; - sha256 = "1111111111111111111111111111111111111111111111111111"; + hash = "sha256-BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="; }; } ``` @@ -76,18 +76,18 @@ The main difference between `fetchurl` and `fetchzip` is in how they store the c - `includes`: Include only files matching these patterns (applies after the above arguments). - `revert`: Revert the patch. -Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `sha256` argument is changed as well. +Note that because the checksum is computed after applying these effects, using or modifying these arguments will have no effect unless the `hash` argument is changed as well. Most other fetchers return a directory rather than a single file. ## `fetchsvn` {#fetchsvn} -Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `sha256`. +Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash`. ## `fetchgit` {#fetchgit} -Used with Git. Expects `url` to a Git repo, `rev`, and `sha256`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`. +Used with Git. Expects `url` to a Git repo, `rev`, and `hash`. `rev` in this case can be full the git commit id (SHA1 hash) or a tag name like `refs/tags/v1.0`. Additionally, the following optional arguments can be given: `fetchSubmodules = true` makes `fetchgit` also fetch the submodules of a repository. If `deepClone` is set to true, the entire repository is cloned as opposing to just creating a shallow clone. `deepClone = true` also implies `leaveDotGit = true` which means that the `.git` directory of the clone won't be removed after checkout. @@ -100,36 +100,36 @@ stdenv.mkDerivation { name = "hello"; src = fetchgit { url = "https://..."; - sparseCheckout = '' - directory/to/be/included - another/directory - ''; - sha256 = "0000000000000000000000000000000000000000000000000000"; + sparseCheckout = [ + "directory/to/be/included" + "another/directory" + ]; + hash = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="; }; } ``` ## `fetchfossil` {#fetchfossil} -Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `sha256`. +Used with Fossil. Expects `url` to a Fossil archive, `rev`, and `hash`. ## `fetchcvs` {#fetchcvs} -Used with CVS. Expects `cvsRoot`, `tag`, and `sha256`. +Used with CVS. Expects `cvsRoot`, `tag`, and `hash`. ## `fetchhg` {#fetchhg} -Used with Mercurial. Expects `url`, `rev`, and `sha256`. +Used with Mercurial. Expects `url`, `rev`, and `hash`. A number of fetcher functions wrap part of `fetchurl` and `fetchzip`. They are mainly convenience functions intended for commonly used destinations of source code in Nixpkgs. These wrapper fetchers are listed below. ## `fetchFromGitea` {#fetchfromgitea} -`fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `sha256` is currently preferred. +`fetchFromGitea` expects five arguments. `domain` is the gitea server name. `owner` is a string corresponding to the Gitea user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every Gitea HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available but `hash` is currently preferred. ## `fetchFromGitHub` {#fetchfromgithub} -`fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `sha256` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `sha256` is currently preferred. +`fetchFromGitHub` expects four arguments. `owner` is a string corresponding to the GitHub user or organization that controls this repository. `repo` corresponds to the name of the software repository. These are located at the top of every GitHub HTML page as `owner`/`repo`. `rev` corresponds to the Git commit hash or tag (e.g `v1.0`) that will be downloaded from Git. Finally, `hash` corresponds to the hash of the extracted directory. Again, other hash algorithms are also available, but `hash` is currently preferred. `fetchFromGitHub` uses `fetchzip` to download the source archive generated by GitHub for the specified revision. If `leaveDotGit`, `deepClone` or `fetchSubmodules` are set to `true`, `fetchFromGitHub` will use `fetchgit` instead. Refer to its section for documentation of these options. @@ -156,7 +156,7 @@ This is used with repo.or.cz repositories. The arguments expected are very simil ## `fetchFromSourcehut` {#fetchfromsourcehut} This is used with sourcehut repositories. Similar to `fetchFromGitHub` above, -it expects `owner`, `repo`, `rev` and `sha256`, but don't forget the tilde (~) +it expects `owner`, `repo`, `rev` and `hash`, but don't forget the tilde (~) in front of the username! Expected arguments also include `vc` ("git" (default) or "hg"), `domain` and `fetchSubmodules`. diff --git a/doc/builders/images.xml b/doc/builders/images.xml index f86ebd86bee4..7d06130e3eca 100644 --- a/doc/builders/images.xml +++ b/doc/builders/images.xml @@ -10,4 +10,5 @@ <xi:include href="images/ocitools.section.xml" /> <xi:include href="images/snaptools.section.xml" /> <xi:include href="images/portableservice.section.xml" /> + <xi:include href="images/makediskimage.section.xml" /> </chapter> diff --git a/doc/builders/images/appimagetools.section.md b/doc/builders/images/appimagetools.section.md index 67e63dc5f61a..0c72315a26e8 100644 --- a/doc/builders/images/appimagetools.section.md +++ b/doc/builders/images/appimagetools.section.md @@ -35,7 +35,7 @@ appimageTools.wrapType2 { # or wrapType1 name = "patchwork"; src = fetchurl { url = "https://github.com/ssbc/patchwork/releases/download/v3.11.4/Patchwork-3.11.4-linux-x86_64.AppImage"; - sha256 = "1blsprpkvm0ws9b96gb36f0rbf8f5jgmw4x6dsb1kswr4ysf591s"; + hash = "sha256-OqTitCeZ6xmWbqYTXp8sDrmVgTNjPZNW0hzUPW++mq4="; }; extraPkgs = pkgs: with pkgs; [ ]; } diff --git a/doc/builders/images/dockertools.section.md b/doc/builders/images/dockertools.section.md index db1a2a214d1e..dfc012b80c5a 100644 --- a/doc/builders/images/dockertools.section.md +++ b/doc/builders/images/dockertools.section.md @@ -62,6 +62,8 @@ The above example will build a Docker image `redis/latest` from the given base i - `config` is used to specify the configuration of the containers that will be started off the built image in Docker. The available options are listed in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions). +- `architecture` is _optional_ and used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`. + - `diskSize` is used to specify the disk size of the VM used to build the image in megabytes. By default it's 1024 MiB. - `buildVMMemorySize` is used to specify the memory size of the VM to build the image in megabytes. By default it's 512 MiB. @@ -141,6 +143,8 @@ Create a Docker image with many of the store paths being on their own layer to i `config` _optional_ +`architecture` is _optional_ and used to specify the image architecture, this is useful for multi-architecture builds that don't need cross compiling. If not specified it will default to `hostPlatform`. + : Run-time configuration of the container. A full list of the options are available at in the [Docker Image Specification v1.2.0](https://github.com/moby/moby/blob/master/image/spec/v1.2.md#image-json-field-descriptions). *Default:* `{}` @@ -245,10 +249,10 @@ Its parameters are described in the example below: pullImage { imageName = "nixos/nix"; imageDigest = - "sha256:20d9485b25ecfd89204e843a962c1bd70e9cc6858d65d7f5fadc340246e2116b"; + "sha256:473a2b527958665554806aea24d0131bacec46d23af09fef4598eeab331850fa"; finalImageName = "nix"; - finalImageTag = "1.11"; - sha256 = "0mqjy3zq2v6rrhizgb9nvhczl87lcfphq9601wcprdika2jz7qh8"; + finalImageTag = "2.11.1"; + sha256 = "sha256-qvhj+Hlmviz+KEBVmsyPIzTB3QlVAFzwAY1zDPIBGxc="; os = "linux"; arch = "x86_64"; } @@ -394,3 +398,142 @@ buildImage { }; } ``` + +## buildNixShellImage {#ssec-pkgs-dockerTools-buildNixShellImage} + +Create a Docker image that sets up an environment similar to that of running `nix-shell` on a derivation. +When run in Docker, this environment somewhat resembles the Nix sandbox typically used by `nix-build`, with a major difference being that access to the internet is allowed. +It additionally also behaves like an interactive `nix-shell`, running things like `shellHook` and setting an interactive prompt. +If the derivation is fully buildable (i.e. `nix-build` can be used on it), running `buildDerivation` inside such a Docker image will build the derivation, with all its outputs being available in the correct `/nix/store` paths, pointed to by the respective environment variables like `$out`, etc. + +::: {.warning} +The behavior doesn't match `nix-shell` or `nix-build` exactly and this function is known not to work correctly for e.g. fixed-output derivations, content-addressed derivations, impure derivations and other special types of derivations. +::: + +### Arguments + +`drv` + +: The derivation on which to base the Docker image. + + Adding packages to the Docker image is possible by e.g. extending the list of `nativeBuildInputs` of this derivation like + + ```nix + buildNixShellImage { + drv = someDrv.overrideAttrs (old: { + nativeBuildInputs = old.nativeBuildInputs or [] ++ [ + somethingExtra + ]; + }); + # ... + } + ``` + + Similarly, you can extend the image initialization script by extending `shellHook` + +`name` _optional_ + +: The name of the resulting image. + + *Default:* `drv.name + "-env"` + +`tag` _optional_ + +: Tag of the generated image. + + *Default:* the resulting image derivation output path's hash + +`uid`/`gid` _optional_ + +: The user/group ID to run the container as. This is like a `nixbld` build user. + + *Default:* 1000/1000 + +`homeDirectory` _optional_ + +: The home directory of the user the container is running as + + *Default:* `/build` + +`shell` _optional_ + +: The path to the `bash` binary to use as the shell. This shell is started when running the image. + + *Default:* `pkgs.bashInteractive + "/bin/bash"` + +`command` _optional_ + +: Run this command in the environment of the derivation, in an interactive shell. See the `--command` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options). + + *Default:* (none) + +`run` _optional_ + +: Same as `command`, but runs the command in a non-interactive shell instead. See the `--run` option in the [`nix-shell` documentation](https://nixos.org/manual/nix/stable/command-ref/nix-shell.html?highlight=nix-shell#options). + + *Default:* (none) + +### Example + +The following shows how to build the `pkgs.hello` package inside a Docker container built with `buildNixShellImage`. + +```nix +with import <nixpkgs> {}; +dockerTools.buildNixShellImage { + drv = hello; +} +``` + +Build the derivation: + +```console +nix-build hello.nix +``` + + these 8 derivations will be built: + /nix/store/xmw3a5ln29rdalavcxk1w3m4zb2n7kk6-nix-shell-rc.drv + ... + Creating layer 56 from paths: ['/nix/store/crpnj8ssz0va2q0p5ibv9i6k6n52gcya-stdenv-linux'] + Creating layer 57 with customisation... + Adding manifests... + Done. + /nix/store/cpyn1lc897ghx0rhr2xy49jvyn52bazv-hello-2.12-env.tar.gz + +Load the image: + +```console +docker load -i result +``` + + 0d9f4c4cd109: Loading layer [==================================================>] 2.56MB/2.56MB + ... + ab1d897c0697: Loading layer [==================================================>] 10.24kB/10.24kB + Loaded image: hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz + +Run the container: + +```console +docker run -it hello-2.12-env:pgj9h98nal555415faa43vsydg161bdz +``` + + [nix-shell:/build]$ + +In the running container, run the build: + +```console +buildDerivation +``` + + unpacking sources + unpacking source archive /nix/store/8nqv6kshb3vs5q5bs2k600xpj5bkavkc-hello-2.12.tar.gz + ... + patching script interpreter paths in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12 + checking for references to /build/ in /nix/store/z5wwy5nagzy15gag42vv61c2agdpz2f2-hello-2.12... + +Check the build result: + +```console +$out/bin/hello +``` + + Hello, world! diff --git a/doc/builders/images/makediskimage.section.md b/doc/builders/images/makediskimage.section.md new file mode 100644 index 000000000000..833a6461e57b --- |