diff options
Diffstat (limited to 'doc/manual/src/command-ref/opt-common.md')
| -rw-r--r-- | doc/manual/src/command-ref/opt-common.md | 221 |
1 files changed, 221 insertions, 0 deletions
diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md new file mode 100644 index 000000000..ac9d996c3 --- /dev/null +++ b/doc/manual/src/command-ref/opt-common.md @@ -0,0 +1,221 @@ +# Common Options + +Most Nix commands accept the following command-line options: + + - `--help` + Prints out a summary of the command syntax and exits. + + - `--version` + Prints out the Nix version number on standard output and exits. + + - `--verbose` / `-v` + Increases the level of verbosity of diagnostic messages printed on + standard error. For each Nix operation, the information printed on + standard output is well-defined; any diagnostic information is + printed on standard error, never on standard output. + + This option may be specified repeatedly. Currently, the following + verbosity levels exist: + + - 0 + “Errors only”: only print messages explaining why the Nix + invocation failed. + + - 1 + “Informational”: print *useful* messages about what Nix is + doing. This is the default. + + - 2 + “Talkative”: print more informational messages. + + - 3 + “Chatty”: print even more informational messages. + + - 4 + “Debug”: print debug information. + + - 5 + “Vomit”: print vast amounts of debug information. + + - `--quiet` + Decreases the level of verbosity of diagnostic messages printed on + standard error. This is the inverse option to `-v` / `--verbose`. + + This option may be specified repeatedly. See the previous verbosity + levels list. + + - `--log-format` format + This option can be used to change the output of the log format, with + format being one of: + + - raw + This is the raw format, as outputted by nix-build. + + - internal-json + Outputs the logs in a structured manner. NOTE: the json schema + is not guarantees to be stable between releases. + + - bar + Only display a progress bar during the builds. + + - bar-with-logs + Display the raw logs, with the progress bar at the bottom. + + - `--no-build-output` / `-Q` + By default, output written by builders to standard output and + standard error is echoed to the Nix command's standard error. This + option suppresses this behaviour. Note that the builder's standard + output and error are always written to a log file in + `prefix/nix/var/log/nix`. + + - `--max-jobs` / `-j` number + Sets the maximum number of build jobs that Nix will perform in + parallel to the specified number. Specify `auto` to use the number + of CPUs in the system. The default is specified by the + [`max-jobs`](#conf-max-jobs) configuration setting, which itself + defaults to `1`. A higher value is useful on SMP systems or to + exploit I/O latency. + + Setting it to `0` disallows building on the local machine, which is + useful when you want builds to happen only on remote builders. + + - `--cores` + Sets the value of the `NIX_BUILD_CORES` environment variable in the + invocation of builders. Builders can use this variable at their + discretion to control the maximum amount of parallelism. For + instance, in Nixpkgs, if the derivation attribute + `enableParallelBuilding` is set to `true`, the builder passes the + `-jN` flag to GNU Make. It defaults to the value of the + [`cores`](#conf-cores) configuration setting, if set, or `1` + otherwise. The value `0` means that the builder should use all + available CPU cores in the system. + + - `--max-silent-time` + Sets the maximum number of seconds that a builder can go without + producing any data on standard output or standard error. The default + is specified by the [`max-silent-time`](#conf-max-silent-time) + configuration setting. `0` means no time-out. + + - `--timeout` + Sets the maximum number of seconds that a builder can run. The + default is specified by the [`timeout`](#conf-timeout) configuration + setting. `0` means no timeout. + + - `--keep-going` / `-k` + Keep going in case of failed builds, to the greatest extent + possible. That is, if building an input of some derivation fails, + Nix will still build the other inputs, but not the derivation + itself. Without this option, Nix stops if any build fails (except + for builds of substitutes), possibly killing builds in progress (in + case of parallel or distributed builds). + + - `--keep-failed` / `-K` + Specifies that in case of a build failure, the temporary directory + (usually in `/tmp`) in which the build takes place should not be + deleted. The path of the build directory is printed as an + informational message. + + - `--fallback` + Whenever Nix attempts to build a derivation for which substitutes + are known for each output path, but realising the output paths + through the substitutes fails, fall back on building the derivation. + + The most common scenario in which this is useful is when we have + registered substitutes in order to perform binary distribution from, + say, a network repository. If the repository is down, the + realisation of the derivation will fail. When this option is + specified, Nix will build the derivation instead. Thus, installation + from binaries falls back on installation from source. This option is + not the default since it is generally not desirable for a transient + failure in obtaining the substitutes to lead to a full build from + source (with the related consumption of resources). + + - `--no-build-hook` + Disables the build hook mechanism. This allows to ignore remote + builders if they are setup on the machine. + + It's useful in cases where the bandwidth between the client and the + remote builder is too low. In that case it can take more time to + upload the sources to the remote builder and fetch back the result + than to do the computation locally. + + - `--readonly-mode` + When this option is used, no attempt is made to open the Nix + database. Most Nix operations do need database access, so those + operations will fail. + + - `--arg` name value + This option is accepted by `nix-env`, `nix-instantiate`, `nix-shell` + and `nix-build`. When evaluating Nix expressions, the expression + evaluator will automatically try to call functions that it + encounters. It can automatically call functions for which every + argument has a [default value](#ss-functions) (e.g., `{ argName ? + defaultValue }: + ...`). With `--arg`, you can also call functions that have arguments + without a default value (or override a default value). That is, if + the evaluator encounters a function with an argument named name, it + will call it with value value. + + For instance, the top-level `default.nix` in Nixpkgs is actually a + function: + + { # The system (e.g., `i686-linux') for which to build the packages. + system ? builtins.currentSystem + ... + }: ... + + So if you call this Nix expression (e.g., when you do `nix-env -i + pkgname`), the function will be called automatically using the value + [`builtins.currentSystem`](#builtin-currentSystem) for the `system` + argument. You can override this using `--arg`, e.g., `nix-env -i + pkgname --arg system + \"i686-freebsd\"`. (Note that since the argument is a Nix string + literal, you have to escape the quotes.) + + - `--argstr` name value + This option is like `--arg`, only the value is not a Nix expression + but a string. So instead of `--arg system \"i686-linux\"` (the outer + quotes are to keep the shell happy) you can say `--argstr system + i686-linux`. + + - `--attr` / `-A` attrPath + Select an attribute from the top-level Nix expression being + evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and + `nix-shell` only.) The *attribute path* attrPath is a sequence of + attribute names separated by dots. For instance, given a top-level + Nix expression e, the attribute path `xorg.xorgserver` would cause + the expression `e.xorg.xorgserver` to be used. See [`nix-env + --install`](#refsec-nix-env-install-examples) for some concrete + examples. + + In addition to attribute names, you can also specify array indices. + For instance, the attribute path `foo.3.bar` selects the `bar` + attribute of the fourth element of the array in the `foo` attribute + of the top-level expression. + + - `--expr` / `-E` + Interpret the command line arguments as a list of Nix expressions to + be parsed and evaluated, rather than as a list of file names of Nix + expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.) + + For `nix-shell`, this option is commonly used to give you a shell in + which you can build the packages returned by the expression. If you + want to get a shell which contain the *built* packages ready for + use, give your expression to the `nix-shell -p` convenience flag + instead. + + - `-I` path + Add a path to the Nix expression search path. This option may be + given multiple times. See the NIX\_PATH\</literal\> environment + variable for information on the semantics of the Nix search path. + Paths added through `-I` take precedence over `NIX_PATH`. + + - `--option` name value + Set the Nix configuration option name to value. This overrides + settings in the Nix configuration file (see nix.conf5). + + - `--repair` + Fix corrupted or missing store paths by redownloading or rebuilding + them. Note that this is slow because it requires computing a + cryptographic hash of the contents of every path in the closure of + the build. Also note the warning under `nix-store --repair-path`. |