mirror of
https://github.com/ilyakooo0/nixpkgs.git
synced 2024-10-15 08:58:58 +03:00
158 lines
6.3 KiB
Markdown
158 lines
6.3 KiB
Markdown
|
# Passthru-attributes {#chap-passthru}
|
|||
|
|
[]{#var-stdenv-passthru} []{#special-variables} <!-- legacy anchors -->
|
|||
|
|
|
|||
|
|
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).
|
|||
|
|
Changing it will not trigger a rebuild – it is "passed through".
|
|||
|
|
Its value can be accessed as if it was set inside a derivation.
|
|||
|
|
|
|||
|
|
::: {.note}
|
|||
|
|
`passthru` attributes follow no particular schema, but there are a few [conventional patterns](#sec-common-passthru-attributes).
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
:::{.example #ex-accessing-passthru}
|
|||
|
|
|
|||
|
|
## Setting and accessing `passthru` attributes
|
|||
|
|
|
|||
|
|
```nix
|
|||
|
|
{ stdenv, fetchGit }:
|
|||
|
|
let
|
|||
|
|
hello = stdenv.mkDerivation {
|
|||
|
|
pname = "hello";
|
|||
|
|
src = fetchGit { /* ... */ };
|
|||
|
|
|
|||
|
|
passthru = {
|
|||
|
|
foo = "bar";
|
|||
|
|
baz = {
|
|||
|
|
value1 = 4;
|
|||
|
|
value2 = 5;
|
|||
|
|
};
|
|||
|
|
};
|
|||
|
|
};
|
|||
|
|
in
|
|||
|
|
hello.baz.value1
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
4
|
|||
|
|
```
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
## Common `passthru`-attributes {#sec-common-passthru-attributes}
|
|||
|
|
|
|||
|
|
Many `passthru` attributes are situational, so this section only lists recurring patterns.
|
|||
|
|
They fall in one of these categories:
|
|||
|
|
|
|||
|
|
- Global conventions, which are applied almost universally in Nixpkgs.
|
|||
|
|
|
|||
|
|
Generally these don't entail any special support built into the derivation they belong to.
|
|||
|
|
Common examples of this type are [`passthru.tests`](#var-passthru-tests) and [`passthru.updateScript`](#var-passthru-updateScript).
|
|||
|
|
|
|||
|
|
- Conventions for adding extra functionality to a derivation.
|
|||
|
|
|
|||
|
|
These tend to entail support from the derivation or the `passthru` attribute in question.
|
|||
|
|
Common examples of this type are `passthru.optional-dependencies`, `passthru.withPlugins`, and `passthru.withPackages`.
|
|||
|
|
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].
|
|||
|
|
|
|||
|
|
Attributes that apply only to particular [build helpers](#part-builders) or [language ecosystems](#chap-language-support) are documented there.
|
|||
|
|
|
|||
|
|
### `passthru.tests` {#var-passthru-tests}
|
|||
|
|
[]{#var-meta-tests} <!-- legacy anchor -->
|
|||
|
|
|
|||
|
|
An attribute set with tests as values.
|
|||
|
|
A test is a derivation that builds when the test passes and fails to build otherwise.
|
|||
|
|
|
|||
|
|
Run these tests with:
|
|||
|
|
|
|||
|
|
```ShellSession
|
|||
|
|
$ cd path/to/nixpkgs
|
|||
|
|
$ nix-build -A your-package.tests
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
:::{.note}
|
|||
|
|
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.
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
#### Package tests {#var-passthru-tests-packages}
|
|||
|
|
[]{#var-meta-tests-packages} <!-- legacy anchor -->
|
|||
|
|
|
|||
|
|
Tests that are part of the source package, if they run quickly, are typically executed in the [`installCheckPhase`](#var-stdenv-phases).
|
|||
|
|
This phase is also suitable for performing a `--version` test for packages that support such flag.
|
|||
|
|
Most programs distributed by Nixpkgs support such a `--version` flag, and successfully calling the program with that flag indicates that the package at least got compiled properly.
|
|||
|
|
|
|||
|
|
:::{.example #ex-checking-build-installCheckPhase}
|
|||
|
|
|
|||
|
|
## Checking builds with `installCheckPhase`
|
|||
|
|
|
|||
|
|
When building `git`, a rudimentary test for successful compilation would be running `git --version`:
|
|||
|
|
|
|||
|
|
```nix
|
|||
|
|
stdenv.mkDerivation (finalAttrs: {
|
|||
|
|
pname = "git";
|
|||
|
|
version = "1.2.3";
|
|||
|
|
# ...
|
|||
|
|
doInstallCheck = true;
|
|||
|
|
installCheckPhase = ''
|
|||
|
|
runHook preInstallCheck
|
|||
|
|
echo checking if 'git --version' mentions ${finalAttrs.version}
|
|||
|
|
$out/bin/git --version | grep ${finalAttrs.version}
|
|||
|
|
runHook postInstallCheck
|
|||
|
|
'';
|
|||
|
|
# ...
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
:::
|
|||
|
|
|
|||
|
|
However, tests that are non-trivial will better fit into `passthru.tests` because they:
|
|||
|
|
|
|||
|
|
- Access the package as consumers would, independently from the environment in which it was built
|
|||
|
|
- Can be run and debugged without rebuilding the package, which is useful if that takes a long time
|
|||
|
|
- Don't add overhad to each build, as opposed to `installCheckPhase`
|
|||
|
|
|
|||
|
|
It is also possible to use `passthru.tests` to test the version with [`testVersion`](#tester-testVersion).
|
|||
|
|
|
|||
|
|
<!-- NOTE(@fricklerhandwerk): one may argue whether that testing guide should rather be in the user's manual -->
|
|||
|
|
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).
|
|||
|
|
|
|||
|
|
#### NixOS tests {#var-passthru-tests-nixos}
|
|||
|
|
[]{#var-meta-tests-nixos} <!-- legacy anchor -->
|
|||
|
|
|
|||
|
|
Tests written for NixOS are available as the `nixosTests` argument to package recipes.
|
|||
|
|
For instance, the [OpenSMTPD derivation](https://search.nixos.org/packages?show=opensmtpd) includes lines similar to:
|
|||
|
|
|
|||
|
|
```nix
|
|||
|
|
{ nixosTests, ... }:
|
|||
|
|
{
|
|||
|
|
# ...
|
|||
|
|
passthru.tests = {
|
|||
|
|
basic-functionality-and-dovecot-integration = nixosTests.opensmtpd;
|
|||
|
|
};
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
NixOS tests run in a virtual machine (VM), so they are slower than regular package tests.
|
|||
|
|
For more information see the NixOS manual on [NixOS module tests](https://nixos.org/manual/nixos/stable/#sec-nixos-tests).
|
|||
|
|
|
|||
|
|
### `passthru.updateScript` {#var-passthru-updateScript}
|
|||
|
|
<!-- legacy anchors -->
|
|||
|
|
[]{#var-passthru-updateScript-command}
|
|||
|
|
[]{#var-passthru-updateScript-set-command}
|
|||
|
|
[]{#var-passthru-updateScript-set-attrPath}
|
|||
|
|
[]{#var-passthru-updateScript-set-supportedFeatures}
|
|||
|
|
[]{#var-passthru-updateScript-env-UPDATE_NIX_NAME}
|
|||
|
|
[]{#var-passthru-updateScript-env-UPDATE_NIX_PNAME}
|
|||
|
|
[]{#var-passthru-updateScript-env-UPDATE_NIX_OLD_VERSION}
|
|||
|
|
[]{#var-passthru-updateScript-env-UPDATE_NIX_ATTR_PATH}
|
|||
|
|
[]{#var-passthru-updateScript-execution}
|
|||
|
|
[]{#var-passthru-updateScript-supported-features}
|
|||
|
|
[]{#var-passthru-updateScript-commit}
|
|||
|
|
[]{#var-passthru-updateScript-commit-attrPath}
|
|||
|
|
[]{#var-passthru-updateScript-commit-oldVersion}
|
|||
|
|
[]{#var-passthru-updateScript-commit-newVersion}
|
|||
|
|
[]{#var-passthru-updateScript-commit-files}
|
|||
|
|
[]{#var-passthru-updateScript-commit-commitBody}
|
|||
|
|
[]{#var-passthru-updateScript-commit-commitMessage}
|
|||
|
|
[]{#var-passthru-updateScript-example-commit}
|
|||
|
|
|
|||
|
|
Nixpkgs tries to automatically update all packages that have an `passthru.updateScript` attribute.
|
|||
|
|
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.
|