doc/stdenv/passthru.chapter.md

   1 # Passthru-attributes {#chap-passthru}
   2 []{#var-stdenv-passthru} []{#special-variables} <!-- legacy anchors -->
   3
   4 As opposed to most other `mkDerivation` input attributes, `passthru` is not passed to the derivation's [`builder` executable](https://nixos.org/manual/nix/stable/expressions/derivations.html#attr-builder).
   5 Changing it will not trigger a rebuild – it is "passed through".
   6 Its value can be accessed as if it was set inside a derivation.
   7
   8 ::: {.note}
   9 `passthru` attributes follow no particular schema, but there are a few [conventional patterns](#sec-common-passthru-attributes).
  10 :::
  11
  12 :::{.example #ex-accessing-passthru}
  13
  14 ## Setting and accessing `passthru` attributes
  15
  16 ```nix
  17 { stdenv, fetchGit }:
  18 let
  19   hello = stdenv.mkDerivation {
  20     pname = "hello";
  21     src = fetchGit { /* ... */ };
  22
  23     passthru = {
  24       foo = "bar";
  25       baz = {
  26         value1 = 4;
  27         value2 = 5;
  28       };
  29     };
  30   };
  31 in
  32 hello.baz.value1
  33 ```
  34
  35 ```
  36 4
  37 ```
  38 :::
  39
  40 ## Common `passthru`-attributes {#sec-common-passthru-attributes}
  41
  42 Many `passthru` attributes are situational, so this section only lists recurring patterns.
  43 They fall in one of these categories:
  44
  45 - Global conventions, which are applied almost universally in Nixpkgs.
  46
  47   Generally these don't entail any special support built into the derivation they belong to.
  48   Common examples of this type are [`passthru.tests`](#var-passthru-tests) and [`passthru.updateScript`](#var-passthru-updateScript).
  49
  50 - Conventions for adding extra functionality to a derivation.
  51
  52   These tend to entail support from the derivation or the `passthru` attribute in question.
  53   Common examples of this type are `passthru.optional-dependencies`, `passthru.withPlugins`, and `passthru.withPackages`.
  54   All of those allow associating the package with a set of components built for that specific package, such as when building Python runtime environments using (`python.withPackages`)[#python.withpackages-function].
  55
  56 Attributes that apply only to particular [build helpers](#part-builders) or [language ecosystems](#chap-language-support) are documented there.
  57
  58 ### `passthru.tests` {#var-passthru-tests}
  59 []{#var-meta-tests} <!-- legacy anchor -->
  60
  61 An attribute set with tests as values.
  62 A test is a derivation that builds when the test passes and fails to build otherwise.
  63
  64 Run these tests with:
  65
  66 ```ShellSession
  67 $ cd path/to/nixpkgs
  68 $ nix-build -A your-package.tests
  69 ```
  70
  71 :::{.note}
  72 The Nixpkgs systems for continuous integration [Hydra](https://hydra.nixos.org/) and [`nixpkgs-review`](https://github.com/Mic92/nixpkgs-review) don't build these derivations by default, and ([`@ofborg`](https://github.com/NixOS/ofborg)) only builds them when evaluating pull requests for that particular package, or when manually instructed.
  73 :::
  74
  75 #### Package tests {#var-passthru-tests-packages}
  76 []{#var-meta-tests-packages} <!-- legacy anchor -->
  77
  78 Besides tests provided by upstream, that you run in the [`checkPhase`](#ssec-check-phase), you may want to define tests derivations in the `passthru.tests` attribute, which won't change the build. `passthru.tests` have several advantages over running tests during any of the [standard phases](#sec-stdenv-phases):
  79
  80 - They access the package as consumers would, independently from the environment in which it was built
  81 - They can be run and debugged without rebuilding the package, which is useful if that takes a long time
  82 - They don't add overhead to each build, as opposed checks added to the [`installCheckPhase`](#ssec-installCheck-phase), such as [`versionCheckHook`](#versioncheckhook).
  83
  84 It is also possible to use `passthru.tests` to test the version with [`testVersion`](#tester-testVersion), but since that is pretty trivial and recommended thing to do, we recommend using [`versionCheckHook`](#versioncheckhook) for that, which has the following advantages over `passthru.tests`:
  85
  86 - If the `versionCheckPhase` (the phase defined by [`versionCheckHook`](#versioncheckhook)) fails, it triggers a failure which can't be ignored if you use the package, or if you find out about it in a [`nixpkgs-review`](https://github.com/Mic92/nixpkgs-review) report.
  87 - Sometimes packages become silently broken - meaning they fail to launch but their build passes because they don't perform any tests in the `checkPhase`. If you use this tool infrequently, such a silent breakage may rot in your system / profile configuration, and you will not notice the failure until you will want to use this package. Testing such basic functionality ensures you have to deal with the failure when you update your system / profile.
  88 - When you open a PR, [ofborg](https://github.com/NixOS/ofborg)'s CI _will_ run `passthru.tests` of [packages that are directly changed by your PR (according to your commits' messages)](https://github.com/NixOS/ofborg?tab=readme-ov-file#automatic-building), but if you'd want to use the [`@ofborg build`](https://github.com/NixOS/ofborg?tab=readme-ov-file#build) command for dependent packages, you won't have to specify in addition the `.tests` attribute of the packages you want to build, and no body will be able to avoid these tests.
  89
  90 <!-- NOTE(@fricklerhandwerk): one may argue whether that testing guide should rather be in the user's manual -->
  91 For more on how to write and run package tests for Nixpkgs, see the [testing section in the package contributor guide](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md#package-tests).
  92
  93 #### NixOS tests {#var-passthru-tests-nixos}
  94 []{#var-meta-tests-nixos} <!-- legacy anchor -->
  95
  96 Tests written for NixOS are available as the `nixosTests` argument to package recipes.
  97 For instance, the [OpenSMTPD derivation](https://search.nixos.org/packages?show=opensmtpd) includes lines similar to:
  98
  99 ```nix
 100 { nixosTests, ... }:
 101 {
 102   # ...
 103   passthru.tests = {
 104     basic-functionality-and-dovecot-integration = nixosTests.opensmtpd;
 105   };
 106 }
 107 ```
 108
 109 NixOS tests run in a virtual machine (VM), so they are slower than regular package tests.
 110 For more information see the NixOS manual on [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).
 111
 112 ### `passthru.updateScript` {#var-passthru-updateScript}
 113 <!-- legacy anchors -->
 114 []{#var-passthru-updateScript-command}
 115 []{#var-passthru-updateScript-set-command}
 116 []{#var-passthru-updateScript-set-attrPath}
 117 []{#var-passthru-updateScript-set-supportedFeatures}
 118 []{#var-passthru-updateScript-env-UPDATE_NIX_NAME}
 119 []{#var-passthru-updateScript-env-UPDATE_NIX_PNAME}
 120 []{#var-passthru-updateScript-env-UPDATE_NIX_OLD_VERSION}
 121 []{#var-passthru-updateScript-env-UPDATE_NIX_ATTR_PATH}
 122 []{#var-passthru-updateScript-execution}
 123 []{#var-passthru-updateScript-supported-features}
 124 []{#var-passthru-updateScript-commit}
 125 []{#var-passthru-updateScript-commit-attrPath}
 126 []{#var-passthru-updateScript-commit-oldVersion}
 127 []{#var-passthru-updateScript-commit-newVersion}
 128 []{#var-passthru-updateScript-commit-files}
 129 []{#var-passthru-updateScript-commit-commitBody}
 130 []{#var-passthru-updateScript-commit-commitMessage}
 131 []{#var-passthru-updateScript-example-commit}
 132
 133 Nixpkgs tries to automatically update all packages that have an `passthru.updateScript` attribute.
 134 See the [section on automatic package updates in the package contributor guide](https://github.com/NixOS/nixpkgs/blob/master/pkgs/README.md#automatic-package-updates) for details.