···169169170170Checks that the output from running a command contains the specified version string in it as a whole word.
171171172172-NOTE: In most cases, [`versionCheckHook`](#versioncheckhook) should be preferred, but this function is provided and documented here anyway. The motivation for adding either tests would be:
172172+NOTE: This is a check you add to `passthru.tests` which is mainly run by OfBorg, but not in Hydra. If you want a version check failure to block the build altogether, then [`versionCheckHook`](#versioncheckhook) is the tool you're looking for (and recommended for quick builds). The motivation for adding either of these checks would be:
173173174174- Catch dynamic linking errors and such and missing environment variables that should be added by wrapping.
175175- Probable protection against accidentally building the wrong version, for example when using an "old" hash in a fixed-output derivation.
+5-1
doc/hooks/versionCheckHook.section.md
···11# versionCheckHook {#versioncheckhook}
2233-This hook adds a `versionCheckPhase` to the [`preInstallCheckHooks`](#ssec-installCheck-phase) that runs the main program of the derivation with a `--help` or `--version` argument, and checks that the `${version}` string is found in that output. You use it like this:
33+This hook adds a `versionCheckPhase` to the [`preInstallCheckHooks`](#ssec-installCheck-phase) that runs the main program of the derivation with a `--help` or `--version` argument, and checks that the `${version}` string is found in that output. If this check fails then the whole build will fail. _(A softer option is [`testers.testVersion`](#tester-testVersion).)_
44+55+You use it like this:
4657```nix
68{
···3335- `versionCheckProgramArg`: The argument that needs to be passed to `versionCheckProgram`. If undefined the hook tries first `--help` and then `--version`. Examples: `version`, `-V`, `-v`.
3436- `preVersionCheck`: A hook to run before the check is done.
3537- `postVersionCheck`: A hook to run after the check is done.
3838+3939+This check assumes the executable is _hermetic_. If environment variables such as `PATH` or `HOME` are required for the program to function, then [`testers.testVersion`](#tester-testVersion) is currently the better alternative.