diff options
Diffstat (limited to 'doc/manual/command-ref')
20 files changed, 0 insertions, 6653 deletions
diff --git a/doc/manual/command-ref/command-ref.xml b/doc/manual/command-ref/command-ref.xml deleted file mode 100644 index cfad9b7d7..000000000 --- a/doc/manual/command-ref/command-ref.xml +++ /dev/null @@ -1,20 +0,0 @@ -<part xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='part-command-ref'> - -<title>Command Reference</title> - -<partintro> -<para>This section lists commands and options that you can use when you -work with Nix.</para> -</partintro> - -<xi:include href="opt-common.xml" /> -<xi:include href="env-common.xml" /> -<xi:include href="main-commands.xml" /> -<xi:include href="utilities.xml" /> -<xi:include href="files.xml" /> - -</part> diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml deleted file mode 100644 index 1fa74a143..000000000 --- a/doc/manual/command-ref/conf-file.xml +++ /dev/null @@ -1,1237 +0,0 @@ -<?xml version="1.0" encoding="utf-8"?> -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="sec-conf-file" - version="5"> - -<refmeta> - <refentrytitle>nix.conf</refentrytitle> - <manvolnum>5</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix.conf</refname> - <refpurpose>Nix configuration file</refpurpose> -</refnamediv> - -<refsection><title>Description</title> - -<para>By default Nix reads settings from the following places:</para> - -<para>The system-wide configuration file -<filename><replaceable>sysconfdir</replaceable>/nix/nix.conf</filename> -(i.e. <filename>/etc/nix/nix.conf</filename> on most systems), or -<filename>$NIX_CONF_DIR/nix.conf</filename> if -<envar>NIX_CONF_DIR</envar> is set. Values loaded in this file are not forwarded to the Nix daemon. The -client assumes that the daemon has already loaded them. -</para> - -<para>User-specific configuration files:</para> - -<para> - If <envar>NIX_USER_CONF_FILES</envar> is set, then each path separated by - <literal>:</literal> will be loaded in reverse order. -</para> - -<para> - Otherwise it will look for <filename>nix/nix.conf</filename> files in - <envar>XDG_CONFIG_DIRS</envar> and <envar>XDG_CONFIG_HOME</envar>. - - The default location is <filename>$HOME/.config/nix.conf</filename> if - those environment variables are unset. -</para> - -<para>The configuration files consist of -<literal><replaceable>name</replaceable> = -<replaceable>value</replaceable></literal> pairs, one per line. Other -files can be included with a line like <literal>include -<replaceable>path</replaceable></literal>, where -<replaceable>path</replaceable> is interpreted relative to the current -conf file and a missing file is an error unless -<literal>!include</literal> is used instead. -Comments start with a <literal>#</literal> character. Here is an -example configuration file:</para> - -<programlisting> -keep-outputs = true # Nice for developers -keep-derivations = true # Idem -</programlisting> - -<para>You can override settings on the command line using the -<option>--option</option> flag, e.g. <literal>--option keep-outputs -false</literal>.</para> - -<para>The following settings are currently available: - -<variablelist> - - - <varlistentry xml:id="conf-allowed-uris"><term><literal>allowed-uris</literal></term> - - <listitem> - - <para>A list of URI prefixes to which access is allowed in - restricted evaluation mode. For example, when set to - <literal>https://github.com/NixOS</literal>, builtin functions - such as <function>fetchGit</function> are allowed to access - <literal>https://github.com/NixOS/patchelf.git</literal>.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-allow-import-from-derivation"><term><literal>allow-import-from-derivation</literal></term> - - <listitem><para>By default, Nix allows you to <function>import</function> from a derivation, - allowing building at evaluation time. With this option set to false, Nix will throw an error - when evaluating an expression that uses this feature, allowing users to ensure their evaluation - will not require any builds to take place.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-allow-new-privileges"><term><literal>allow-new-privileges</literal></term> - - <listitem><para>(Linux-specific.) By default, builders on Linux - cannot acquire new privileges by calling setuid/setgid programs or - programs that have file capabilities. For example, programs such - as <command>sudo</command> or <command>ping</command> will - fail. (Note that in sandbox builds, no such programs are available - unless you bind-mount them into the sandbox via the - <option>sandbox-paths</option> option.) You can allow the - use of such programs by enabling this option. This is impure and - usually undesirable, but may be useful in certain scenarios - (e.g. to spin up containers or set up userspace network interfaces - in tests).</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-allowed-users"><term><literal>allowed-users</literal></term> - - <listitem> - - <para>A list of names of users (separated by whitespace) that - are allowed to connect to the Nix daemon. As with the - <option>trusted-users</option> option, you can specify groups by - prefixing them with <literal>@</literal>. Also, you can allow - all users by specifying <literal>*</literal>. The default is - <literal>*</literal>.</para> - - <para>Note that trusted users are always allowed to connect.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-auto-optimise-store"><term><literal>auto-optimise-store</literal></term> - - <listitem><para>If set to <literal>true</literal>, Nix - automatically detects files in the store that have identical - contents, and replaces them with hard links to a single copy. - This saves disk space. If set to <literal>false</literal> (the - default), you can still run <command>nix-store - --optimise</command> to get rid of duplicate - files.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-builders"> - <term><literal>builders</literal></term> - <listitem> - <para>A list of machines on which to perform builds. <phrase - condition="manual">See <xref linkend="chap-distributed-builds" - /> for details.</phrase></para> - </listitem> - </varlistentry> - - - <varlistentry xml:id="conf-builders-use-substitutes"><term><literal>builders-use-substitutes</literal></term> - - <listitem><para>If set to <literal>true</literal>, Nix will instruct - remote build machines to use their own binary substitutes if available. In - practical terms, this means that remote hosts will fetch as many build - dependencies as possible from their own substitutes (e.g, from - <literal>cache.nixos.org</literal>), instead of waiting for this host to - upload them all. This can drastically reduce build times if the network - connection between this computer and the remote build host is slow. Defaults - to <literal>false</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-build-users-group"><term><literal>build-users-group</literal></term> - - <listitem><para>This options specifies the Unix group containing - the Nix build user accounts. In multi-user Nix installations, - builds should not be performed by the Nix account since that would - allow users to arbitrarily modify the Nix store and database by - supplying specially crafted builders; and they cannot be performed - by the calling user since that would allow him/her to influence - the build result.</para> - - <para>Therefore, if this option is non-empty and specifies a valid - group, builds will be performed under the user accounts that are a - member of the group specified here (as listed in - <filename>/etc/group</filename>). Those user accounts should not - be used for any other purpose!</para> - - <para>Nix will never run two builds under the same user account at - the same time. This is to prevent an obvious security hole: a - malicious user writing a Nix expression that modifies the build - result of a legitimate Nix expression being built by another user. - Therefore it is good to have as many Nix build user accounts as - you can spare. (Remember: uids are cheap.)</para> - - <para>The build users should have permission to create files in - the Nix store, but not delete them. Therefore, - <filename>/nix/store</filename> should be owned by the Nix - account, its group should be the group specified here, and its - mode should be <literal>1775</literal>.</para> - - <para>If the build users group is empty, builds will be performed - under the uid of the Nix process (that is, the uid of the caller - if <envar>NIX_REMOTE</envar> is empty, the uid under which the Nix - daemon runs if <envar>NIX_REMOTE</envar> is - <literal>daemon</literal>). Obviously, this should not be used in - multi-user settings with untrusted users.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-compress-build-log"><term><literal>compress-build-log</literal></term> - - <listitem><para>If set to <literal>true</literal> (the default), - build logs written to <filename>/nix/var/log/nix/drvs</filename> - will be compressed on the fly using bzip2. Otherwise, they will - not be compressed.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-connect-timeout"><term><literal>connect-timeout</literal></term> - - <listitem> - - <para>The timeout (in seconds) for establishing connections in - the binary cache substituter. It corresponds to - <command>curl</command>’s <option>--connect-timeout</option> - option.</para> - - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-cores"><term><literal>cores</literal></term> - - <listitem><para>Sets the value of the - <envar>NIX_BUILD_CORES</envar> 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 - <varname>enableParallelBuilding</varname> is set to - <literal>true</literal>, the builder passes the - <option>-j<replaceable>N</replaceable></option> flag to GNU Make. - It can be overridden using the <option - linkend='opt-cores'>--cores</option> command line switch and - defaults to <literal>1</literal>. The value <literal>0</literal> - means that the builder should use all available CPU cores in the - system.</para> - - <para>See also <xref linkend="chap-tuning-cores-and-jobs" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-diff-hook"><term><literal>diff-hook</literal></term> - <listitem> - <para> - Absolute path to an executable capable of diffing build results. - The hook executes if <xref linkend="conf-run-diff-hook" /> is - true, and the output of a build is known to not be the same. - This program is not executed to determine if two results are the - same. - </para> - - <para> - The diff hook is executed by the same user and group who ran the - build. However, the diff hook does not have write access to the - store path just built. - </para> - - <para>The diff hook program receives three parameters:</para> - - <orderedlist> - <listitem> - <para> - A path to the previous build's results - </para> - </listitem> - - <listitem> - <para> - A path to the current build's results - </para> - </listitem> - - <listitem> - <para> - The path to the build's derivation - </para> - </listitem> - - <listitem> - <para> - The path to the build's scratch directory. This directory - will exist only if the build was run with - <option>--keep-failed</option>. - </para> - </listitem> - </orderedlist> - - <para> - The stderr and stdout output from the diff hook will not be - displayed to the user. Instead, it will print to the nix-daemon's - log. - </para> - - <para>When using the Nix daemon, <literal>diff-hook</literal> must - be set in the <filename>nix.conf</filename> configuration file, and - cannot be passed at the command line. - </para> - </listitem> - </varlistentry> - - <varlistentry xml:id="conf-enforce-determinism"> - <term><literal>enforce-determinism</literal></term> - - <listitem><para>See <xref linkend="conf-repeat" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-extra-sandbox-paths"> - <term><literal>extra-sandbox-paths</literal></term> - - <listitem><para>A list of additional paths appended to - <option>sandbox-paths</option>. Useful if you want to extend - its default value.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-extra-platforms"><term><literal>extra-platforms</literal></term> - - <listitem><para>Platforms other than the native one which - this machine is capable of building for. This can be useful for - supporting additional architectures on compatible machines: - i686-linux can be built on x86_64-linux machines (and the default - for this setting reflects this); armv7 is backwards-compatible with - armv6 and armv5tel; some aarch64 machines can also natively run - 32-bit ARM code; and qemu-user may be used to support non-native - platforms (though this may be slow and buggy). Most values for this - are not enabled by default because build systems will often - misdetect the target platform and generate incompatible code, so you - may wish to cross-check the results of using this option against - proper natively-built versions of your - derivations.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-extra-substituters"><term><literal>extra-substituters</literal></term> - - <listitem><para>Additional binary caches appended to those - specified in <option>substituters</option>. When used by - unprivileged users, untrusted substituters (i.e. those not listed - in <option>trusted-substituters</option>) are silently - ignored.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-fallback"><term><literal>fallback</literal></term> - - <listitem><para>If set to <literal>true</literal>, Nix will fall - back to building from source if a binary substitute fails. This - is equivalent to the <option>--fallback</option> flag. The - default is <literal>false</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-fsync-metadata"><term><literal>fsync-metadata</literal></term> - - <listitem><para>If set to <literal>true</literal>, changes to the - Nix store metadata (in <filename>/nix/var/nix/db</filename>) are - synchronously flushed to disk. This improves robustness in case - of system crashes, but reduces performance. The default is - <literal>true</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-hashed-mirrors"><term><literal>hashed-mirrors</literal></term> - - <listitem><para>A list of web servers used by - <function>builtins.fetchurl</function> to obtain files by - hash. The default is - <literal>http://tarballs.nixos.org/</literal>. Given a hash type - <replaceable>ht</replaceable> and a base-16 hash - <replaceable>h</replaceable>, Nix will try to download the file - from - <literal>hashed-mirror/<replaceable>ht</replaceable>/<replaceable>h</replaceable></literal>. - This allows files to be downloaded even if they have disappeared - from their original URI. For example, given the default mirror - <literal>http://tarballs.nixos.org/</literal>, when building the derivation - -<programlisting> -builtins.fetchurl { - url = "https://example.org/foo-1.2.3.tar.xz"; - sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"; -} -</programlisting> - - Nix will attempt to download this file from - <literal>http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae</literal> - first. If it is not available there, if will try the original URI.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-http-connections"><term><literal>http-connections</literal></term> - - <listitem><para>The maximum number of parallel TCP connections - used to fetch files from binary caches and by other downloads. It - defaults to 25. 0 means no limit.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-keep-build-log"><term><literal>keep-build-log</literal></term> - - <listitem><para>If set to <literal>true</literal> (the default), - Nix will write the build log of a derivation (i.e. the standard - output and error of its builder) to the directory - <filename>/nix/var/log/nix/drvs</filename>. The build log can be - retrieved using the command <command>nix-store -l - <replaceable>path</replaceable></command>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-keep-derivations"><term><literal>keep-derivations</literal></term> - - <listitem><para>If <literal>true</literal> (default), the garbage - collector will keep the derivations from which non-garbage store - paths were built. If <literal>false</literal>, they will be - deleted unless explicitly registered as a root (or reachable from - other roots).</para> - - <para>Keeping derivation around is useful for querying and - traceability (e.g., it allows you to ask with what dependencies or - options a store path was built), so by default this option is on. - Turn it off to save a bit of disk space (or a lot if - <literal>keep-outputs</literal> is also turned on).</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-keep-env-derivations"><term><literal>keep-env-derivations</literal></term> - - <listitem><para>If <literal>false</literal> (default), derivations - are not stored in Nix user environments. That is, the derivations of - any build-time-only dependencies may be garbage-collected.</para> - - <para>If <literal>true</literal>, when you add a Nix derivation to - a user environment, the path of the derivation is stored in the - user environment. Thus, the derivation will not be - garbage-collected until the user environment generation is deleted - (<command>nix-env --delete-generations</command>). To prevent - build-time-only dependencies from being collected, you should also - turn on <literal>keep-outputs</literal>.</para> - - <para>The difference between this option and - <literal>keep-derivations</literal> is that this one is - “sticky”: it applies to any user environment created while this - option was enabled, while <literal>keep-derivations</literal> - only applies at the moment the garbage collector is - run.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-keep-outputs"><term><literal>keep-outputs</literal></term> - - <listitem><para>If <literal>true</literal>, the garbage collector - will keep the outputs of non-garbage derivations. If - <literal>false</literal> (default), outputs will be deleted unless - they are GC roots themselves (or reachable from other roots).</para> - - <para>In general, outputs must be registered as roots separately. - However, even if the output of a derivation is registered as a - root, the collector will still delete store paths that are used - only at build time (e.g., the C compiler, or source tarballs - downloaded from the network). To prevent it from doing so, set - this option to <literal>true</literal>.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-max-build-log-size"><term><literal>max-build-log-size</literal></term> - - <listitem> - - <para>This option defines the maximum number of bytes that a - builder can write to its stdout/stderr. If the builder exceeds - this limit, it’s killed. A value of <literal>0</literal> (the - default) means that there is no limit.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-max-free"><term><literal>max-free</literal></term> - - <listitem><para>When a garbage collection is triggered by the - <literal>min-free</literal> option, it stops as soon as - <literal>max-free</literal> bytes are available. The default is - infinity (i.e. delete all garbage).</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-max-jobs"><term><literal>max-jobs</literal></term> - - <listitem><para>This option defines the maximum number of jobs - that Nix will try to build in parallel. The default is - <literal>1</literal>. The special value <literal>auto</literal> - causes Nix to use the number of CPUs in your system. <literal>0</literal> - is useful when using remote builders to prevent any local builds (except for - <literal>preferLocalBuild</literal> derivation attribute which executes locally - regardless). It can be - overridden using the <option - linkend='opt-max-jobs'>--max-jobs</option> (<option>-j</option>) - command line switch.</para> - - <para>See also <xref linkend="chap-tuning-cores-and-jobs" />.</para> - </listitem> - </varlistentry> - - <varlistentry xml:id="conf-max-silent-time"><term><literal>max-silent-time</literal></term> - - <listitem> - - <para>This option defines the maximum number of seconds that a - builder can go without producing any data on standard output or - standard error. This is useful (for instance in an automated - build system) to catch builds that are stuck in an infinite - loop, or to catch remote builds that are hanging due to network - problems. It can be overridden using the <option - linkend="opt-max-silent-time">--max-silent-time</option> command - line switch.</para> - - <para>The value <literal>0</literal> means that there is no - timeout. This is also the default.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-min-free"><term><literal>min-free</literal></term> - - <listitem> - <para>When free disk space in <filename>/nix/store</filename> - drops below <literal>min-free</literal> during a build, Nix - performs a garbage-collection until <literal>max-free</literal> - bytes are available or there is no more garbage. A value of - <literal>0</literal> (the default) disables this feature.</para> - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-narinfo-cache-negative-ttl"><term><literal>narinfo-cache-negative-ttl</literal></term> - - <listitem> - - <para>The TTL in seconds for negative lookups. If a store path is - queried from a substituter but was not found, there will be a - negative lookup cached in the local disk cache database for the - specified duration.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-narinfo-cache-positive-ttl"><term><literal>narinfo-cache-positive-ttl</literal></term> - - <listitem> - - <para>The TTL in seconds for positive lookups. If a store path is - queried from a substituter, the result of the query will be cached - in the local disk cache database including some of the NAR - metadata. The default TTL is a month, setting a shorter TTL for - positive lookups can be useful for binary caches that have - frequent garbage collection, in which case having a more frequent - cache invalidation would prevent trying to pull the path again and - failing with a hash mismatch if the build isn't reproducible. - </para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-netrc-file"><term><literal>netrc-file</literal></term> - - <listitem><para>If set to an absolute path to a <filename>netrc</filename> - file, Nix will use the HTTP authentication credentials in this file when - trying to download from a remote host through HTTP or HTTPS. Defaults to - <filename>$NIX_CONF_DIR/netrc</filename>.</para> - - <para>The <filename>netrc</filename> file consists of a list of - accounts in the following format: - -<screen> -machine <replaceable>my-machine</replaceable> -login <replaceable>my-username</replaceable> -password <replaceable>my-password</replaceable> -</screen> - - For the exact syntax, see <link - xlink:href="https://ec.haxx.se/usingcurl-netrc.html">the - <literal>curl</literal> documentation.</link></para> - - <note><para>This must be an absolute path, and <literal>~</literal> - is not resolved. For example, <filename>~/.netrc</filename> won't - resolve to your home directory's <filename>.netrc</filename>.</para></note> - </listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-plugin-files"> - <term><literal>plugin-files</literal></term> - <listitem> - <para> - A list of plugin files to be loaded by Nix. Each of these - files will be dlopened by Nix, allowing them to affect - execution through static initialization. In particular, these - plugins may construct static instances of RegisterPrimOp to - add new primops or constants to the expression language, - RegisterStoreImplementation to add new store implementations, - RegisterCommand to add new subcommands to the - <literal>nix</literal> command, and RegisterSetting to add new - nix config settings. See the constructors for those types for - more details. - </para> - <para> - Since these files are loaded into the same address space as - Nix itself, they must be DSOs compatible with the instance of - Nix running at the time (i.e. compiled against the same - headers, not linked to any incompatible libraries). They - should not be linked to any Nix libs directly, as those will - be available already at load time. - </para> - <para> - If an entry in the list is a directory, all files in the - directory are loaded as plugins (non-recursively). - </para> - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-pre-build-hook"><term><literal>pre-build-hook</literal></term> - - <listitem> - - - <para>If set, the path to a program that can set extra - derivation-specific settings for this system. This is used for settings - that can't be captured by the derivation model itself and are too variable - between different versions of the same system to be hard-coded into nix. - </para> - - <para>The hook is passed the derivation path and, if sandboxes are enabled, - the sandbox directory. It can then modify the sandbox and send a series of - commands to modify various settings to stdout. The currently recognized - commands are:</para> - - <variablelist> - <varlistentry xml:id="extra-sandbox-paths"> - <term><literal>extra-sandbox-paths</literal></term> - - <listitem> - - <para>Pass a list of files and directories to be included in the - sandbox for this build. One entry per line, terminated by an empty - line. Entries have the same format as - <literal>sandbox-paths</literal>.</para> - - </listitem> - - </varlistentry> - </variablelist> - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-post-build-hook"> - <term><literal>post-build-hook</literal></term> - <listitem> - <para>Optional. The path to a program to execute after each build.</para> - - <para>This option is only settable in the global - <filename>nix.conf</filename>, or on the command line by trusted - users.</para> - - <para>When using the nix-daemon, the daemon executes the hook as - <literal>root</literal>. If the nix-daemon is not involved, the - hook runs as the user executing the nix-build.</para> - - <itemizedlist> - <listitem><para>The hook executes after an evaluation-time build.</para></listitem> - <listitem><para>The hook does not execute on substituted paths.</para></listitem> - <listitem><para>The hook's output always goes to the user's terminal.</para></listitem> - <listitem><para>If the hook fails, the build succeeds but no further builds execute.</para></listitem> - <listitem><para>The hook executes synchronously, and blocks other builds from progressing while it runs.</para></listitem> - </itemizedlist> - - <para>The program executes with no arguments. The program's environment - contains the following environment variables:</para> - - <variablelist> - <varlistentry> - <term><envar>DRV_PATH</envar></term> - <listitem> - <para>The derivation for the built paths.</para> - <para>Example: - <literal>/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv</literal> - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><envar>OUT_PATHS</envar></term> - <listitem> - <para>Output paths of the built derivation, separated by a space character.</para> - <para>Example: - <literal>/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev - /nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc - /nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info - /nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man - /nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23</literal>. - </para> - </listitem> - </varlistentry> - </variablelist> - - <para>See <xref linkend="chap-post-build-hook" /> for an example - implementation.</para> - - </listitem> - </varlistentry> - - <varlistentry xml:id="conf-repeat"><term><literal>repeat</literal></term> - - <listitem><para>How many times to repeat builds to check whether - they are deterministic. The default value is 0. If the value is - non-zero, every build is repeated the specified number of - times. If the contents of any of the runs differs from the - previous ones and <xref linkend="conf-enforce-determinism" /> is - true, the build is rejected and the resulting store paths are not - registered as “valid” in Nix’s database.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-require-sigs"><term><literal>require-sigs</literal></term> - - <listitem><para>If set to <literal>true</literal> (the default), - any non-content-addressed path added or copied to the Nix store - (e.g. when substituting from a binary cache) must have a valid - signature, that is, be signed using one of the keys listed in - <option>trusted-public-keys</option> or - <option>secret-key-files</option>. Set to <literal>false</literal> - to disable signature checking.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-restrict-eval"><term><literal>restrict-eval</literal></term> - - <listitem> - - <para>If set to <literal>true</literal>, the Nix evaluator will - not allow access to any files outside of the Nix search path (as - set via the <envar>NIX_PATH</envar> environment variable or the - <option>-I</option> option), or to URIs outside of - <option>allowed-uri</option>. The default is - <literal>false</literal>.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-run-diff-hook"><term><literal>run-diff-hook</literal></term> - <listitem> - <para> - If true, enable the execution of <xref linkend="conf-diff-hook" />. - </para> - - <para> - When using the Nix daemon, <literal>run-diff-hook</literal> must - be set in the <filename>nix.conf</filename> configuration file, - and cannot be passed at the command line. - </para> - </listitem> - </varlistentry> - - <varlistentry xml:id="conf-sandbox"><term><literal>sandbox</literal></term> - - <listitem><para>If set to <literal>true</literal>, builds will be - performed in a <emphasis>sandboxed environment</emphasis>, i.e., - they’re isolated from the normal file system hierarchy and will - only see their dependencies in the Nix store, the temporary build - directory, private versions of <filename>/proc</filename>, - <filename>/dev</filename>, <filename>/dev/shm</filename> and - <filename>/dev/pts</filename> (on Linux), and the paths configured with the - <link linkend='conf-sandbox-paths'><literal>sandbox-paths</literal> - option</link>. This is useful to prevent undeclared dependencies - on files in directories such as <filename>/usr/bin</filename>. In - addition, on Linux, builds run in private PID, mount, network, IPC - and UTS namespaces to isolate them from other processes in the - system (except that fixed-output derivations do not run in private - network namespace to ensure they can access the network).</para> - - <para>Currently, sandboxing only work on Linux and macOS. The use - of a sandbox requires that Nix is run as root (so you should use - the <link linkend='conf-build-users-group'>“build users” - feature</link> to perform the actual builds under different users - than root).</para> - - <para>If this option is set to <literal>relaxed</literal>, then - fixed-output derivations and derivations that have the - <varname>__noChroot</varname> attribute set to - <literal>true</literal> do not run in sandboxes.</para> - - <para>The default is <literal>true</literal> on Linux and - <literal>false</literal> on all other platforms.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-sandbox-dev-shm-size"><term><literal>sandbox-dev-shm-size</literal></term> - - <listitem><para>This option determines the maximum size of the - <literal>tmpfs</literal> filesystem mounted on - <filename>/dev/shm</filename> in Linux sandboxes. For the format, - see the description of the <option>size</option> option of - <literal>tmpfs</literal> in - <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>. The - default is <literal>50%</literal>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-sandbox-paths"> - <term><literal>sandbox-paths</literal></term> - - <listitem><para>A list of paths bind-mounted into Nix sandbox - environments. You can use the syntax - <literal><replaceable>target</replaceable>=<replaceable>source</replaceable></literal> - to mount a path in a different location in the sandbox; for - instance, <literal>/bin=/nix-bin</literal> will mount the path - <literal>/nix-bin</literal> as <literal>/bin</literal> inside the - sandbox. If <replaceable>source</replaceable> is followed by - <literal>?</literal>, then it is not an error if - <replaceable>source</replaceable> does not exist; for example, - <literal>/dev/nvidiactl?</literal> specifies that - <filename>/dev/nvidiactl</filename> will only be mounted in the - sandbox if it exists in the host filesystem.</para> - - <para>Depending on how Nix was built, the default value for this option - may be empty or provide <filename>/bin/sh</filename> as a - bind-mount of <command>bash</command>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-secret-key-files"><term><literal>secret-key-files</literal></term> - - <listitem><para>A whitespace-separated list of files containing - secret (private) keys. These are used to sign locally-built - paths. They can be generated using <command>nix-store - --generate-binary-cache-key</command>. The corresponding public - key can be distributed to other users, who can add it to - <option>trusted-public-keys</option> in their - <filename>nix.conf</filename>.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-show-trace"><term><literal>show-trace</literal></term> - - <listitem><para>Causes Nix to print out a stack trace in case of Nix - expression evaluation errors.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-substitute"><term><literal>substitute</literal></term> - - <listitem><para>If set to <literal>true</literal> (default), Nix - will use binary substitutes if available. This option can be - disabled to force building from source.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-stalled-download-timeout"><term><literal>stalled-download-timeout</literal></term> - <listitem> - <para>The timeout (in seconds) for receiving data from servers - during download. Nix cancels idle downloads after this timeout's - duration.</para> - </listitem> - </varlistentry> - - <varlistentry xml:id="conf-substituters"><term><literal>substituters</literal></term> - - <listitem><para>A list of URLs of substituters, separated by - whitespace. The default is - <literal>https://cache.nixos.org</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-system"><term><literal>system</literal></term> - - <listitem><para>This option specifies the canonical Nix system - name of the current installation, such as - <literal>i686-linux</literal> or - <literal>x86_64-darwin</literal>. Nix can only build derivations - whose <literal>system</literal> attribute equals the value - specified here. In general, it never makes sense to modify this - value from its default, since you can use it to ‘lie’ about the - platform you are building on (e.g., perform a Mac OS build on a - Linux machine; the result would obviously be wrong). It only - makes sense if the Nix binaries can run on multiple platforms, - e.g., ‘universal binaries’ that run on <literal>x86_64-linux</literal> and - <literal>i686-linux</literal>.</para> - - <para>It defaults to the canonical Nix system name detected by - <filename>configure</filename> at build time.</para></listitem> - - </varlistentry> - - - <varlistentry xml:id="conf-system-features"><term><literal>system-features</literal></term> - - <listitem><para>A set of system “features” supported by this - machine, e.g. <literal>kvm</literal>. Derivations can express a - dependency on such features through the derivation attribute - <varname>requiredSystemFeatures</varname>. For example, the - attribute - -<programlisting> -requiredSystemFeatures = [ "kvm" ]; -</programlisting> - - ensures that the derivation can only be built on a machine with - the <literal>kvm</literal> feature.</para> - - <para>This setting by default includes <literal>kvm</literal> if - <filename>/dev/kvm</filename> is accessible, and the - pseudo-features <literal>nixos-test</literal>, - <literal>benchmark</literal> and <literal>big-parallel</literal> - that are used in Nixpkgs to route builds to specific - machines.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-tarball-ttl"><term><literal>tarball-ttl</literal></term> - - <listitem> - <para>Default: <literal>3600</literal> seconds.</para> - - <para>The number of seconds a downloaded tarball is considered - fresh. If the cached tarball is stale, Nix will check whether - it is still up to date using the ETag header. Nix will download - a new version if the ETag header is unsupported, or the - cached ETag doesn't match. - </para> - - <para>Setting the TTL to <literal>0</literal> forces Nix to always - check if the tarball is up to date.</para> - - <para>Nix caches tarballs in - <filename>$XDG_CACHE_HOME/nix/tarballs</filename>.</para> - - <para>Files fetched via <envar>NIX_PATH</envar>, - <function>fetchGit</function>, <function>fetchMercurial</function>, - <function>fetchTarball</function>, and <function>fetchurl</function> - respect this TTL. - </para> - </listitem> - </varlistentry> - - <varlistentry xml:id="conf-timeout"><term><literal>timeout</literal></term> - - <listitem> - - <para>This option defines the maximum number of seconds that a - builder can run. This is useful (for instance in an automated - build system) to catch builds that are stuck in an infinite loop - but keep writing to their standard output or standard error. It - can be overridden using the <option - linkend="opt-timeout">--timeout</option> command line - switch.</para> - - <para>The value <literal>0</literal> means that there is no - timeout. This is also the default.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-trace-function-calls"><term><literal>trace-function-calls</literal></term> - - <listitem> - - <para>Default: <literal>false</literal>.</para> - - <para>If set to <literal>true</literal>, the Nix evaluator will - trace every function call. Nix will print a log message at the - "vomit" level for every function entrance and function exit.</para> - - <informalexample><screen> -function-trace entered undefined position at 1565795816999559622 -function-trace exited undefined position at 1565795816999581277 -function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150 -function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684 -</screen></informalexample> - - <para>The <literal>undefined position</literal> means the function - call is a builtin.</para> - - <para>Use the <literal>contrib/stack-collapse.py</literal> script - distributed with the Nix source code to convert the trace logs - in to a format suitable for <command>flamegraph.pl</command>.</para> - - </listitem> - - </varlistentry> - - <varlistentry xml:id="conf-trusted-public-keys"><term><literal>trusted-public-keys</literal></term> - - <listitem><para>A whitespace-separated list of public keys. When - paths are copied from another Nix store (such as a binary cache), - they must be signed with one of these keys. For example: - <literal>cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= - hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-trusted-substituters"><term><literal>trusted-substituters</literal></term> - - <listitem><para>A list of URLs of substituters, separated by - whitespace. These are not used by default, but can be enabled by - users of the Nix daemon by specifying <literal>--option - substituters <replaceable>urls</replaceable></literal> on the - command line. Unprivileged users are only allowed to pass a - subset of the URLs listed in <literal>substituters</literal> and - <literal>trusted-substituters</literal>.</para></listitem> - - </varlistentry> - - <varlistentry xml:id="conf-trusted-users"><term><literal>trusted-users</literal></term> - - <listitem> - - <para>A list of names of users (separated by whitespace) that - have additional rights when connecting to the Nix daemon, such - as the ability to specify additional binary caches, or to import - unsigned NARs. You can also specify groups by prefixing them - with <literal>@</literal>; for instance, - <literal>@wheel</literal> means all users in the - <literal>wheel</literal> group. The default is - <literal>root</literal>.</para> - - <warning><para>Adding a user to <option>trusted-users</option> - is essentially equivalent to giving that user root access to the - system. For example, the user can set - <option>sandbox-paths</option> and thereby obtain read access to - directories that are otherwise inacessible to - them.</para></warning> - - </listitem> - - </varlistentry> - -</variablelist> -</para> - -<refsection> - <title>Deprecated Settings</title> - -<para> - -<variablelist> - - <varlistentry xml:id="conf-binary-caches"> - <term><literal>binary-caches</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>binary-caches</literal> is now an alias to - <xref linkend="conf-substituters" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-binary-cache-public-keys"> - <term><literal>binary-cache-public-keys</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>binary-cache-public-keys</literal> is now an alias to - <xref linkend="conf-trusted-public-keys" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-compress-log"> - <term><literal>build-compress-log</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-compress-log</literal> is now an alias to - <xref linkend="conf-compress-build-log" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-cores"> - <term><literal>build-cores</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-cores</literal> is now an alias to - <xref linkend="conf-cores" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-extra-chroot-dirs"> - <term><literal>build-extra-chroot-dirs</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-extra-chroot-dirs</literal> is now an alias to - <xref linkend="conf-extra-sandbox-paths" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-extra-sandbox-paths"> - <term><literal>build-extra-sandbox-paths</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-extra-sandbox-paths</literal> is now an alias to - <xref linkend="conf-extra-sandbox-paths" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-fallback"> - <term><literal>build-fallback</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-fallback</literal> is now an alias to - <xref linkend="conf-fallback" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-max-jobs"> - <term><literal>build-max-jobs</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-max-jobs</literal> is now an alias to - <xref linkend="conf-max-jobs" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-max-log-size"> - <term><literal>build-max-log-size</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-max-log-size</literal> is now an alias to - <xref linkend="conf-max-build-log-size" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-max-silent-time"> - <term><literal>build-max-silent-time</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-max-silent-time</literal> is now an alias to - <xref linkend="conf-max-silent-time" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-repeat"> - <term><literal>build-repeat</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-repeat</literal> is now an alias to - <xref linkend="conf-repeat" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-timeout"> - <term><literal>build-timeout</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-timeout</literal> is now an alias to - <xref linkend="conf-timeout" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-use-chroot"> - <term><literal>build-use-chroot</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-use-chroot</literal> is now an alias to - <xref linkend="conf-sandbox" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-use-sandbox"> - <term><literal>build-use-sandbox</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-use-sandbox</literal> is now an alias to - <xref linkend="conf-sandbox" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-build-use-substitutes"> - <term><literal>build-use-substitutes</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>build-use-substitutes</literal> is now an alias to - <xref linkend="conf-substitute" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-gc-keep-derivations"> - <term><literal>gc-keep-derivations</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>gc-keep-derivations</literal> is now an alias to - <xref linkend="conf-keep-derivations" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-gc-keep-outputs"> - <term><literal>gc-keep-outputs</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>gc-keep-outputs</literal> is now an alias to - <xref linkend="conf-keep-outputs" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-env-keep-derivations"> - <term><literal>env-keep-derivations</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>env-keep-derivations</literal> is now an alias to - <xref linkend="conf-keep-env-derivations" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-extra-binary-caches"> - <term><literal>extra-binary-caches</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>extra-binary-caches</literal> is now an alias to - <xref linkend="conf-extra-substituters" />.</para></listitem> - </varlistentry> - - <varlistentry xml:id="conf-trusted-binary-caches"> - <term><literal>trusted-binary-caches</literal></term> - - <listitem><para><emphasis>Deprecated:</emphasis> - <literal>trusted-binary-caches</literal> is now an alias to - <xref linkend="conf-trusted-substituters" />.</para></listitem> - </varlistentry> -</variablelist> -</para> -</refsection> - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/env-common.xml b/doc/manual/command-ref/env-common.xml deleted file mode 100644 index 8466cc463..000000000 --- a/doc/manual/command-ref/env-common.xml +++ /dev/null @@ -1,209 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-common-env"> - -<title>Common Environment Variables</title> - - -<para>Most Nix commands interpret the following environment variables:</para> - -<variablelist xml:id="env-common"> - -<varlistentry><term><envar>IN_NIX_SHELL</envar></term> - - <listitem><para>Indicator that tells if the current environment was set up by - <command>nix-shell</command>. Since Nix 2.0 the values are - <literal>"pure"</literal> and <literal>"impure"</literal></para></listitem> - -</varlistentry> - -<varlistentry xml:id="env-NIX_PATH"><term><envar>NIX_PATH</envar></term> - - <listitem> - - <para>A colon-separated list of directories used to look up Nix - expressions enclosed in angle brackets (i.e., - <literal><<replaceable>path</replaceable>></literal>). For - instance, the value - - <screen> -/home/eelco/Dev:/etc/nixos</screen> - - will cause Nix to look for paths relative to - <filename>/home/eelco/Dev</filename> and - <filename>/etc/nixos</filename>, in this order. It is also - possible to match paths against a prefix. For example, the value - - <screen> -nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos</screen> - - will cause Nix to search for - <literal><nixpkgs/<replaceable>path</replaceable>></literal> in - <filename>/home/eelco/Dev/nixpkgs-branch/<replaceable>path</replaceable></filename> - and - <filename>/etc/nixos/nixpkgs/<replaceable>path</replaceable></filename>.</para> - - <para>If a path in the Nix search path starts with - <literal>http://</literal> or <literal>https://</literal>, it is - interpreted as the URL of a tarball that will be downloaded and - unpacked to a temporary location. The tarball must consist of a - single top-level directory. For example, setting - <envar>NIX_PATH</envar> to - - <screen> -nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz</screen> - - tells Nix to download the latest revision in the Nixpkgs/NixOS - 15.09 channel.</para> - - <para>A following shorthand can be used to refer to the official channels: - - <screen>nixpkgs=channel:nixos-15.09</screen> - </para> - - <para>The search path can be extended using the <option - linkend="opt-I">-I</option> option, which takes precedence over - <envar>NIX_PATH</envar>.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term> - - <listitem> - - <para>Normally, the Nix store directory (typically - <filename>/nix/store</filename>) is not allowed to contain any - symlink components. This is to prevent “impure” builds. Builders - sometimes “canonicalise” paths by resolving all symlink components. - Thus, builds on different machines (with - <filename>/nix/store</filename> resolving to different locations) - could yield different results. This is generally not a problem, - except when builds are deployed to machines where - <filename>/nix/store</filename> resolves differently. If you are - sure that you’re not going to do that, you can set - <envar>NIX_IGNORE_SYMLINK_STORE</envar> to <envar>1</envar>.</para> - - <para>Note that if you’re symlinking the Nix store so that you can - put it on another file system than the root file system, on Linux - you’re better off using <literal>bind</literal> mount points, e.g., - - <screen> -$ mkdir /nix -$ mount -o bind /mnt/otherdisk/nix /nix</screen> - - Consult the <citerefentry><refentrytitle>mount</refentrytitle> - <manvolnum>8</manvolnum></citerefentry> manual page for details.</para> - - </listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_STORE_DIR</envar></term> - - <listitem><para>Overrides the location of the Nix store (default - <filename><replaceable>prefix</replaceable>/store</filename>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_DATA_DIR</envar></term> - - <listitem><para>Overrides the location of the Nix static data - directory (default - <filename><replaceable>prefix</replaceable>/share</filename>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_LOG_DIR</envar></term> - - <listitem><para>Overrides the location of the Nix log directory - (default <filename><replaceable>prefix</replaceable>/var/log/nix</filename>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_STATE_DIR</envar></term> - - <listitem><para>Overrides the location of the Nix state directory - (default <filename><replaceable>prefix</replaceable>/var/nix</filename>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_CONF_DIR</envar></term> - - <listitem><para>Overrides the location of the system Nix configuration - directory (default - <filename><replaceable>prefix</replaceable>/etc/nix</filename>).</para></listitem> - -</varlistentry> - -<varlistentry><term><envar>NIX_USER_CONF_FILES</envar></term> - - <listitem><para>Overrides the location of the user Nix configuration files - to load from (defaults to the XDG spec locations). The variable is treated - as a list separated by the <literal>:</literal> token.</para></listitem> - -</varlistentry> - -<varlistentry><term><envar>TMPDIR</envar></term> - - <listitem><para>Use the specified directory to store temporary - files. In particular, this includes temporary build directories; - these can take up substantial amounts of disk space. The default is - <filename>/tmp</filename>.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="envar-remote"><term><envar>NIX_REMOTE</envar></term> - - <listitem><para>This variable should be set to - <literal>daemon</literal> if you want to use the Nix daemon to - execute Nix operations. This is necessary in <link - linkend="ssec-multi-user">multi-user Nix installations</link>. - If the Nix daemon's Unix socket is at some non-standard path, - this variable should be set to <literal>unix://path/to/socket</literal>. - Otherwise, it should be left unset.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_SHOW_STATS</envar></term> - - <listitem><para>If set to <literal>1</literal>, Nix will print some - evaluation statistics, such as the number of values - allocated.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>NIX_COUNT_CALLS</envar></term> - - <listitem><para>If set to <literal>1</literal>, Nix will print how - often functions were called during Nix expression evaluation. This - is useful for profiling your Nix expressions.</para></listitem> - -</varlistentry> - - -<varlistentry><term><envar>GC_INITIAL_HEAP_SIZE</envar></term> - - <listitem><para>If Nix has been configured to use the Boehm garbage - collector, this variable sets the initial size of the heap in bytes. - It defaults to 384 MiB. Setting it to a low value reduces memory - consumption, but will increase runtime due to the overhead of - garbage collection.</para></listitem> - -</varlistentry> - - -</variablelist> - - -</chapter> diff --git a/doc/manual/command-ref/files.xml b/doc/manual/command-ref/files.xml deleted file mode 100644 index 7bbc96e89..000000000 --- a/doc/manual/command-ref/files.xml +++ /dev/null @@ -1,14 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='ch-files'> - -<title>Files</title> - -<para>This section lists configuration files that you can use when you -work with Nix.</para> - -<xi:include href="conf-file.xml" /> - -</chapter>
\ No newline at end of file diff --git a/doc/manual/command-ref/main-commands.xml b/doc/manual/command-ref/main-commands.xml deleted file mode 100644 index 0f4169243..000000000 --- a/doc/manual/command-ref/main-commands.xml +++ /dev/null @@ -1,17 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='ch-main-commands'> - -<title>Main Commands</title> - -<para>This section lists commands and options that you can use when you -work with Nix.</para> - -<xi:include href="nix-env.xml" /> -<xi:include href="nix-build.xml" /> -<xi:include href="nix-shell.xml" /> -<xi:include href="nix-store.xml" /> - -</chapter>
\ No newline at end of file diff --git a/doc/manual/command-ref/nix-build.xml b/doc/manual/command-ref/nix-build.xml deleted file mode 100644 index 886d25910..000000000 --- a/doc/manual/command-ref/nix-build.xml +++ /dev/null @@ -1,190 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-build"> - -<refmeta> - <refentrytitle>nix-build</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-build</refname> - <refpurpose>build a Nix expression</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-build</command> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - <replaceable>attrPath</replaceable> - </arg> - <arg><option>--no-out-link</option></arg> - <arg><option>--dry-run</option></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--out-link</option></arg> - <arg choice='plain'><option>-o</option></arg> - </group> - <replaceable>outlink</replaceable> - </arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>The <command>nix-build</command> command builds the derivations -described by the Nix expressions in <replaceable>paths</replaceable>. -If the build succeeds, it places a symlink to the result in the -current directory. The symlink is called <filename>result</filename>. -If there are multiple Nix expressions, or the Nix expressions evaluate -to multiple derivations, multiple sequentially numbered symlinks are -created (<filename>result</filename>, <filename>result-2</filename>, -and so on).</para> - -<para>If no <replaceable>paths</replaceable> are specified, then -<command>nix-build</command> will use <filename>default.nix</filename> -in the current directory, if it exists.</para> - -<para>If an element of <replaceable>paths</replaceable> starts with -<literal>http://</literal> or <literal>https://</literal>, it is -interpreted as the URL of a tarball that will be downloaded and -unpacked to a temporary location. The tarball must include a single -top-level directory containing at least a file named -<filename>default.nix</filename>.</para> - -<para><command>nix-build</command> is essentially a wrapper around -<link -linkend="sec-nix-instantiate"><command>nix-instantiate</command></link> -(to translate a high-level Nix expression to a low-level store -derivation) and <link -linkend="rsec-nix-store-realise"><command>nix-store ---realise</command></link> (to build the store derivation).</para> - -<warning><para>The result of the build is automatically registered as -a root of the Nix garbage collector. This root disappears -automatically when the <filename>result</filename> symlink is deleted -or renamed. So don’t rename the symlink.</para></warning> - -</refsection> - - -<refsection><title>Options</title> - -<para>All options not listed here are passed to <command>nix-store ---realise</command>, except for <option>--arg</option> and -<option>--attr</option> / <option>-A</option> which are passed to -<command>nix-instantiate</command>. <phrase condition="manual">See -also <xref linkend="sec-common-options" />.</phrase></para> - -<variablelist> - - <varlistentry><term><option>--no-out-link</option></term> - - <listitem><para>Do not create a symlink to the output path. Note - that as a result the output does not become a root of the garbage - collector, and so might be deleted by <command>nix-store - --gc</command>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--dry-run</option></term> - <listitem><para>Show what store paths would be built or downloaded.</para></listitem> - </varlistentry> - - <varlistentry xml:id='opt-out-link'><term><option>--out-link</option> / - <option>-o</option> <replaceable>outlink</replaceable></term> - - <listitem><para>Change the name of the symlink to the output path - created from <filename>result</filename> to - <replaceable>outlink</replaceable>.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>The following common options are supported:</para> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-build '<nixpkgs>' -A firefox -store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv -/nix/store/d18hyl92g30l...-firefox-1.5.0.7 - -$ ls -l result -lrwxrwxrwx <replaceable>...</replaceable> result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7 - -$ ls ./result/bin/ -firefox firefox-config</screen> - -<para>If a derivation has multiple outputs, -<command>nix-build</command> will build the default (first) output. -You can also build all outputs: -<screen> -$ nix-build '<nixpkgs>' -A openssl.all -</screen> -This will create a symlink for each output named -<filename>result-<replaceable>outputname</replaceable></filename>. -The suffix is omitted if the output name is <literal>out</literal>. -So if <literal>openssl</literal> has outputs <literal>out</literal>, -<literal>bin</literal> and <literal>man</literal>, -<command>nix-build</command> will create symlinks -<literal>result</literal>, <literal>result-bin</literal> and -<literal>result-man</literal>. It’s also possible to build a specific -output: -<screen> -$ nix-build '<nixpkgs>' -A openssl.man -</screen> -This will create a symlink <literal>result-man</literal>.</para> - -<para>Build a Nix expression given on the command line: - -<screen> -$ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"' -$ cat ./result -bar -</screen> - -</para> - -<para>Build the GNU Hello package from the latest revision of the -master branch of Nixpkgs: - -<screen> -$ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello -</screen> - -</para> - -</refsection> - - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml deleted file mode 100644 index ebcf56aff..000000000 --- a/doc/manual/command-ref/nix-channel.xml +++ /dev/null @@ -1,181 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-channel"> - -<refmeta> - <refentrytitle>nix-channel</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-channel</refname> - <refpurpose>manage Nix channels</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-channel</command> - <group choice='req'> - <arg choice='plain'><option>--add</option> <replaceable>url</replaceable> <arg choice='opt'><replaceable>name</replaceable></arg></arg> - <arg choice='plain'><option>--remove</option> <replaceable>name</replaceable></arg> - <arg choice='plain'><option>--list</option></arg> - <arg choice='plain'><option>--update</option> <arg rep='repeat'><replaceable>names</replaceable></arg></arg> - <arg choice='plain'><option>--rollback</option> <arg choice='opt'><replaceable>generation</replaceable></arg></arg> - </group> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>A Nix channel is a mechanism that allows you to automatically -stay up-to-date with a set of pre-built Nix expressions. A Nix -channel is just a URL that points to a place containing a set of Nix -expressions. <phrase condition="manual">See also <xref -linkend="sec-channels" />.</phrase></para> - -<para>To see the list of official NixOS channels, visit <link -xlink:href="https://nixos.org/channels" />.</para> - -<para>This command has the following operations: - -<variablelist> - - <varlistentry><term><option>--add</option> <replaceable>url</replaceable> [<replaceable>name</replaceable>]</term> - - <listitem><para>Adds a channel named - <replaceable>name</replaceable> with URL - <replaceable>url</replaceable> to the list of subscribed channels. - If <replaceable>name</replaceable> is omitted, it defaults to the - last component of <replaceable>url</replaceable>, with the - suffixes <literal>-stable</literal> or - <literal>-unstable</literal> removed.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--remove</option> <replaceable>name</replaceable></term> - - <listitem><para>Removes the channel named - <replaceable>name</replaceable> from the list of subscribed - channels.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--list</option></term> - - <listitem><para>Prints the names and URLs of all subscribed - channels on standard output.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--update</option> [<replaceable>names</replaceable>…]</term> - - <listitem><para>Downloads the Nix expressions of all subscribed - channels (or only those included in - <replaceable>names</replaceable> if specified) and makes them the - default for <command>nix-env</command> operations (by symlinking - them from the directory - <filename>~/.nix-defexpr</filename>).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--rollback</option> [<replaceable>generation</replaceable>]</term> - - <listitem><para>Reverts the previous call to <command>nix-channel - --update</command>. Optionally, you can specify a specific channel - generation number to restore.</para></listitem> - - </varlistentry> - -</variablelist> - -</para> - -<para>Note that <option>--add</option> does not automatically perform -an update.</para> - -<para>The list of subscribed channels is stored in -<filename>~/.nix-channels</filename>.</para> - -</refsection> - -<refsection><title>Examples</title> - -<para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para> - -<screen> -$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable -$ nix-channel --update -$ nix-env -iA nixpkgs.hello</screen> - -<para>You can revert channel updates using <option>--rollback</option>:</para> - -<screen> -$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' -"14.04.527.0e935f1" - -$ nix-channel --rollback -switching from generation 483 to 482 - -$ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version' -"14.04.526.dbadfad" -</screen> - -</refsection> - -<refsection><title>Files</title> - -<variablelist> - - <varlistentry><term><filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename></term> - - <listitem><para><command>nix-channel</command> uses a - <command>nix-env</command> profile to keep track of previous - versions of the subscribed channels. Every time you run - <command>nix-channel --update</command>, a new channel generation - (that is, a symlink to the channel Nix expressions in the Nix store) - is created. This enables <command>nix-channel --rollback</command> - to revert to previous versions.</para></listitem> - - </varlistentry> - - <varlistentry><term><filename>~/.nix-defexpr/channels</filename></term> - - <listitem><para>This is a symlink to - <filename>/nix/var/nix/profiles/per-user/<replaceable>username</replaceable>/channels</filename>. It - ensures that <command>nix-env</command> can find your channels. In - a multi-user installation, you may also have - <filename>~/.nix-defexpr/channels_root</filename>, which links to - the channels of the root user.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - -<refsection><title>Channel format</title> - -<para>A channel URL should point to a directory containing the -following files:</para> - -<variablelist> - - <varlistentry><term><filename>nixexprs.tar.xz</filename></term> - - <listitem><para>A tarball containing Nix expressions and files - referenced by them (such as build scripts and patches). At the - top level, the tarball should contain a single directory. That - directory must contain a file <filename>default.nix</filename> - that serves as the channel’s “entry point”.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/nix-collect-garbage.xml b/doc/manual/command-ref/nix-collect-garbage.xml deleted file mode 100644 index 43e068796..000000000 --- a/doc/manual/command-ref/nix-collect-garbage.xml +++ /dev/null @@ -1,63 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-collect-garbage"> - -<refmeta> - <refentrytitle>nix-collect-garbage</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-collect-garbage</refname> - <refpurpose>delete unreachable store paths</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-collect-garbage</command> - <arg><option>--delete-old</option></arg> - <arg><option>-d</option></arg> - <arg><option>--delete-older-than</option> <replaceable>period</replaceable></arg> - <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg> - <arg><option>--dry-run</option></arg> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>The command <command>nix-collect-garbage</command> is mostly an -alias of <link linkend="rsec-nix-store-gc"><command>nix-store ---gc</command></link>, that is, it deletes all unreachable paths in -the Nix store to clean up your system. However, it provides two -additional options: <option>-d</option> (<option>--delete-old</option>), -which deletes all old generations of all profiles in -<filename>/nix/var/nix/profiles</filename> by invoking -<literal>nix-env --delete-generations old</literal> on all profiles -(of course, this makes rollbacks to previous configurations -impossible); and -<option>--delete-older-than</option> <replaceable>period</replaceable>, -where period is a value such as <literal>30d</literal>, which deletes -all generations older than the specified number of days in all profiles -in <filename>/nix/var/nix/profiles</filename> (except for the generations -that were active at that point in time). -</para> - -</refsection> - -<refsection><title>Example</title> - -<para>To delete from the Nix store everything that is not used by the -current generations of each profile, do - -<screen> -$ nix-collect-garbage -d</screen> - -</para> - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/nix-copy-closure.xml b/doc/manual/command-ref/nix-copy-closure.xml deleted file mode 100644 index e6dcf180a..000000000 --- a/doc/manual/command-ref/nix-copy-closure.xml +++ /dev/null @@ -1,169 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - xml:id="sec-nix-copy-closure"> - -<refmeta> - <refentrytitle>nix-copy-closure</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-copy-closure</refname> - <refpurpose>copy a closure to or from a remote machine via SSH</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-copy-closure</command> - <group> - <arg choice='plain'><option>--to</option></arg> - <arg choice='plain'><option>--from</option></arg> - </group> - <arg><option>--gzip</option></arg> - <!-- - <arg><option>- -show-progress</option></arg> - --> - <arg><option>--include-outputs</option></arg> - <group> - <arg choice='plain'><option>--use-substitutes</option></arg> - <arg choice='plain'><option>-s</option></arg> - </group> - <arg><option>-v</option></arg> - <arg choice='plain'> - <replaceable>user@</replaceable><replaceable>machine</replaceable> - </arg> - <arg choice='plain'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para><command>nix-copy-closure</command> gives you an easy and -efficient way to exchange software between machines. Given one or -more Nix store <replaceable>paths</replaceable> on the local -machine, <command>nix-copy-closure</command> computes the closure of -those paths (i.e. all their dependencies in the Nix store), and copies -all paths in the closure to the remote machine via the -<command>ssh</command> (Secure Shell) command. With the -<option>--from</option>, the direction is reversed: -the closure of <replaceable>paths</replaceable> on a remote machine is -copied to the Nix store on the local machine.</para> - -<para>This command is efficient because it only sends the store paths -that are missing on the target machine.</para> - -<para>Since <command>nix-copy-closure</command> calls -<command>ssh</command>, you may be asked to type in the appropriate -password or passphrase. In fact, you may be asked -<emphasis>twice</emphasis> because <command>nix-copy-closure</command> -currently connects twice to the remote machine, first to get the set -of paths missing on the target machine, and second to send the dump of -those paths. If this bothers you, use -<command>ssh-agent</command>.</para> - - -<refsection><title>Options</title> - -<variablelist> - - <varlistentry><term><option>--to</option></term> - - <listitem><para>Copy the closure of - <replaceable>paths</replaceable> from the local Nix store to the - Nix store on <replaceable>machine</replaceable>. This is the - default.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--from</option></term> - - <listitem><para>Copy the closure of - <replaceable>paths</replaceable> from the Nix store on - <replaceable>machine</replaceable> to the local Nix - store.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--gzip</option></term> - - <listitem><para>Enable compression of the SSH - connection.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--include-outputs</option></term> - - <listitem><para>Also copy the outputs of store derivations - included in the closure.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--use-substitutes</option> / <option>-s</option></term> - - <listitem><para>Attempt to download missing paths on the target - machine using Nix’s substitute mechanism. Any paths that cannot - be substituted on the target are still copied normally from the - source. This is useful, for instance, if the connection between - the source and target machine is slow, but the connection between - the target machine and <literal>nixos.org</literal> (the default - binary cache server) is fast.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>-v</option></term> - - <listitem><para>Show verbose output.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Environment variables</title> - -<variablelist> - - <varlistentry><term><envar>NIX_SSHOPTS</envar></term> - - <listitem><para>Additional options to be passed to - <command>ssh</command> on the command line.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Copy Firefox with all its dependencies to a remote machine: - -<screen> -$ nix-copy-closure --to alice@itchy.labs $(type -tP firefox)</screen> - -</para> - -<para>Copy Subversion from a remote machine and then install it into a -user environment: - -<screen> -$ nix-copy-closure --from alice@itchy.labs \ - /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4 -$ nix-env -i /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4 -</screen> - -</para> - -</refsection> - - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/nix-daemon.xml b/doc/manual/command-ref/nix-daemon.xml deleted file mode 100644 index a2161f033..000000000 --- a/doc/manual/command-ref/nix-daemon.xml +++ /dev/null @@ -1,35 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-daemon"> - -<refmeta> - <refentrytitle>nix-daemon</refentrytitle> - <manvolnum>8</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-daemon</refname> - <refpurpose>Nix multi-user support daemon</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-daemon</command> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The Nix daemon is necessary in multi-user Nix installations. It -performs build actions and other operations on the Nix store on behalf -of unprivileged users.</para> - - -</refsection> - -</refentry> diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml deleted file mode 100644 index 55f25d959..000000000 --- a/doc/manual/command-ref/nix-env.xml +++ /dev/null @@ -1,1503 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-env"> - -<refmeta> - <refentrytitle>nix-env</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-env</refname> - <refpurpose>manipulate or query Nix user environments</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-env</command> - <xi:include href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--file</option></arg> - <arg choice='plain'><option>-f</option></arg> - </group> - <replaceable>path</replaceable> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--profile</option></arg> - <arg choice='plain'><option>-p</option></arg> - </group> - <replaceable>path</replaceable> - </arg> - <arg> - <arg choice='plain'><option>--system-filter</option></arg> - <replaceable>system</replaceable> - </arg> - <arg><option>--dry-run</option></arg> - <arg choice='plain'><replaceable>operation</replaceable></arg> - <arg rep='repeat'><replaceable>options</replaceable></arg> - <arg rep='repeat'><replaceable>arguments</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The command <command>nix-env</command> is used to manipulate Nix -user environments. User environments are sets of software packages -available to a user at some point in time. In other words, they are a -synthesised view of the programs available in the Nix store. There -may be many user environments: different users can have different -environments, and individual users can switch between different -environments.</para> - -<para><command>nix-env</command> takes exactly one -<emphasis>operation</emphasis> flag which indicates the subcommand to -be performed. These are documented below.</para> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Selectors</title> - -<para>Several commands, such as <command>nix-env -q</command> and -<command>nix-env -i</command>, take a list of arguments that specify -the packages on which to operate. These are extended regular -expressions that must match the entire name of the package. (For -details on regular expressions, see -<citerefentry><refentrytitle>regex</refentrytitle><manvolnum>7</manvolnum></citerefentry>.) -The match is case-sensitive. The regular expression can optionally be -followed by a dash and a version number; if omitted, any version of -the package will match. Here are some examples: - -<variablelist> - - <varlistentry> - <term><literal>firefox</literal></term> - <listitem><para>Matches the package name - <literal>firefox</literal> and any version.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>firefox-32.0</literal></term> - <listitem><para>Matches the package name - <literal>firefox</literal> and version - <literal>32.0</literal>.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>gtk\\+</literal></term> - <listitem><para>Matches the package name - <literal>gtk+</literal>. The <literal>+</literal> character must - be escaped using a backslash to prevent it from being interpreted - as a quantifier, and the backslash must be escaped in turn with - another backslash to ensure that the shell passes it - on.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>.\*</literal></term> - <listitem><para>Matches any package name. This is the default for - most commands.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>'.*zip.*'</literal></term> - <listitem><para>Matches any package name containing the string - <literal>zip</literal>. Note the dots: <literal>'*zip*'</literal> - does not work, because in a regular expression, the character - <literal>*</literal> is interpreted as a - quantifier.</para></listitem> - </varlistentry> - - <varlistentry> - <term><literal>'.*(firefox|chromium).*'</literal></term> - <listitem><para>Matches any package name containing the strings - <literal>firefox</literal> or - <literal>chromium</literal>.</para></listitem> - </varlistentry> - -</variablelist> - -</para> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Common options</title> - -<para>This section lists the options that are common to all -operations. These options are allowed for every subcommand, though -they may not always have an effect. <phrase condition="manual">See -also <xref linkend="sec-common-options" />.</phrase></para> - -<variablelist> - - <varlistentry><term><option>--file</option> / <option>-f</option> <replaceable>path</replaceable></term> - - <listitem><para>Specifies the Nix expression (designated below as - the <emphasis>active Nix expression</emphasis>) used by the - <option>--install</option>, <option>--upgrade</option>, and - <option>--query --available</option> operations to obtain - derivations. The default is - <filename>~/.nix-defexpr</filename>.</para> - - <para>If the argument starts with <literal>http://</literal> or - <literal>https://</literal>, it is interpreted as the URL of a - tarball that will be downloaded and unpacked to a temporary - location. The tarball must include a single top-level directory - containing at least a file named <filename>default.nix</filename>.</para> - - </listitem> - - </varlistentry> - - <varlistentry><term><option>--profile</option> / <option>-p</option> <replaceable>path</replaceable></term> - - <listitem><para>Specifies the profile to be used by those - operations that operate on a profile (designated below as the - <emphasis>active profile</emphasis>). A profile is a sequence of - user environments called <emphasis>generations</emphasis>, one of - which is the <emphasis>current - generation</emphasis>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--dry-run</option></term> - - <listitem><para>For the <option>--install</option>, - <option>--upgrade</option>, <option>--uninstall</option>, - <option>--switch-generation</option>, - <option>--delete-generations</option> and - <option>--rollback</option> operations, this flag will cause - <command>nix-env</command> to print what - <emphasis>would</emphasis> be done if this flag had not been - specified, without actually doing it.</para> - - <para><option>--dry-run</option> also prints out which paths will - be <link linkend="gloss-substitute">substituted</link> (i.e., - downloaded) and which paths will be built from source (because no - substitute is available).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term> - - <listitem><para>By default, operations such as <option>--query - --available</option> show derivations matching any platform. This - option allows you to use derivations for the specified platform - <replaceable>system</replaceable>.</para></listitem> - - </varlistentry> - -</variablelist> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Files</title> - -<variablelist> - - <varlistentry><term><filename>~/.nix-defexpr</filename></term> - - <listitem><para>The source for the default Nix - expressions used by the <option>--install</option>, - <option>--upgrade</option>, and <option>--query - --available</option> operations to obtain derivations. The - <option>--file</option> option may be used to override this - default.</para> - - <para>If <filename>~/.nix-defexpr</filename> is a file, - it is loaded as a Nix expression. If the expression - is a set, it is used as the default Nix expression. - If the expression is a function, an empty set is passed - as argument and the return value is used as - the default Nix expression.</para> - - <para>If <filename>~/.nix-defexpr</filename> is a directory - containing a <filename>default.nix</filename> file, that file - is loaded as in the above paragraph.</para> - - <para>If <filename>~/.nix-defexpr</filename> is a directory without - a <filename>default.nix</filename> file, then its contents - (both files and subdirectories) are loaded as Nix expressions. - The expressions are combined into a single set, each expression - under an attribute with the same name as the original file - or subdirectory. - </para> - - <para>For example, if <filename>~/.nix-defexpr</filename> contains - two files, <filename>foo.nix</filename> and <filename>bar.nix</filename>, - then the default Nix expression will essentially be - -<programlisting> -{ - foo = import ~/.nix-defexpr/foo.nix; - bar = import ~/.nix-defexpr/bar.nix; -}</programlisting> - - </para> - - <para>The file <filename>manifest.nix</filename> is always ignored. - Subdirectories without a <filename>default.nix</filename> file - are traversed recursively in search of more Nix expressions, - but the names of these intermediate directories are not - added to the attribute paths of the default Nix expression.</para> - - <para>The command <command>nix-channel</command> places symlinks - to the downloaded Nix expressions from each subscribed channel in - this directory.</para> - </listitem> - - </varlistentry> - - <varlistentry><term><filename>~/.nix-profile</filename></term> - - <listitem><para>A symbolic link to the user's current profile. By - default, this symlink points to - <filename><replaceable>prefix</replaceable>/var/nix/profiles/default</filename>. - The <envar>PATH</envar> environment variable should include - <filename>~/.nix-profile/bin</filename> for the user environment - to be visible to the user.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id="rsec-nix-env-install"><title>Operation <option>--install</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--install</option></arg> - <arg choice='plain'><option>-i</option></arg> - </group> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <group choice='opt'> - <arg choice='plain'><option>--preserve-installed</option></arg> - <arg choice='plain'><option>-P</option></arg> - </group> - <group choice='opt'> - <arg choice='plain'><option>--remove-all</option></arg> - <arg choice='plain'><option>-r</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>The install operation creates a new user environment, based on -the current generation of the active profile, to which a set of store -paths described by <replaceable>args</replaceable> is added. The -arguments <replaceable>args</replaceable> map to store paths in a -number of possible ways: - -<itemizedlist> - - <listitem><para>By default, <replaceable>args</replaceable> is a set - of derivation names denoting derivations in the active Nix - expression. These are realised, and the resulting output paths are - installed. Currently installed derivations with a name equal to the - name of a derivation being added are removed unless the option - <option>--preserve-installed</option> is - specified.</para> - - <para>If there are multiple derivations matching a name in - <replaceable>args</replaceable> that have the same name (e.g., - <literal>gcc-3.3.6</literal> and <literal>gcc-4.1.1</literal>), then - the derivation with the highest <emphasis>priority</emphasis> is - used. A derivation can define a priority by declaring the - <varname>meta.priority</varname> attribute. This attribute should - be a number, with a higher value denoting a lower priority. The - default priority is <literal>0</literal>.</para> - - <para>If there are multiple matching derivations with the same - priority, then the derivation with the highest version will be - installed.</para> - - <para>You can force the installation of multiple derivations with - the same name by being specific about the versions. For instance, - <literal>nix-env -i gcc-3.3.6 gcc-4.1.1</literal> will install both - version of GCC (and will probably cause a user environment - conflict!).</para></listitem> - - <listitem><para>If <link - linkend='opt-attr'><option>--attr</option></link> - (<option>-A</option>) is specified, the arguments are - <emphasis>attribute paths</emphasis> that select attributes from the - top-level Nix expression. This is faster than using derivation - names and unambiguous. To find out the attribute paths of available - packages, use <literal>nix-env -qaP</literal>.</para></listitem> - - <listitem><para>If <option>--from-profile</option> - <replaceable>path</replaceable> is given, - <replaceable>args</replaceable> is a set of names denoting installed - store paths in the profile <replaceable>path</replaceable>. This is - an easy way to copy user environment elements from one profile to - another.</para></listitem> - - <listitem><para>If <option>--from-expression</option> is given, - <replaceable>args</replaceable> are Nix <link - linkend="ss-functions">functions</link> that are called with the - active Nix expression as their single argument. The derivations - returned by those function calls are installed. This allows - derivations to be specified in an unambiguous way, which is necessary - if there are multiple derivations with the same - name.</para></listitem> - - <listitem><para>If <replaceable>args</replaceable> are store - derivations, then these are <link - linkend="rsec-nix-store-realise">realised</link>, and the resulting - output paths are installed.</para></listitem> - - <listitem><para>If <replaceable>args</replaceable> are store paths - that are not store derivations, then these are <link - linkend="rsec-nix-store-realise">realised</link> and - installed.</para></listitem> - - <listitem><para>By default all outputs are installed for each derivation. - That can be reduced by setting <literal>meta.outputsToInstall</literal>. - </para></listitem> <!-- TODO: link nixpkgs docs on the ability to override those. --> - -</itemizedlist> - -</para> - -</refsection> - - -<refsection><title>Flags</title> - -<variablelist> - - <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term> - - <listitem><para>Use only derivations for which a substitute is - registered, i.e., there is a pre-built binary available that can - be downloaded in lieu of building the derivation. Thus, no - packages will be built from source.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--preserve-installed</option></term> - <term><option>-P</option></term> - - <listitem><para>Do not remove derivations with a name matching one - of the derivations being installed. Usually, trying to have two - versions of the same package installed in the same generation of a - profile will lead to an error in building the generation, due to - file name clashes between the two versions. However, this is not - the case for all packages.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--remove-all</option></term> - <term><option>-r</option></term> - - <listitem><para>Remove all previously installed packages first. - This is equivalent to running <literal>nix-env -e '.*'</literal> - first, except that everything happens in a single - transaction.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection xml:id='refsec-nix-env-install-examples'><title>Examples</title> - -<para>To install a specific version of <command>gcc</command> from the -active Nix expression: - -<screen> -$ nix-env --install gcc-3.3.2 -installing `gcc-3.3.2' -uninstalling `gcc-3.1'</screen> - -Note the previously installed version is removed, since -<option>--preserve-installed</option> was not specified.</para> - -<para>To install an arbitrary version: - -<screen> -$ nix-env --install gcc -installing `gcc-3.3.2'</screen> - -</para> - -<para>To install using a specific attribute: - -<screen> -$ nix-env -i -A gcc40mips -$ nix-env -i -A xorg.xorgserver</screen> - -</para> - -<para>To install all derivations in the Nix expression <filename>foo.nix</filename>: - -<screen> -$ nix-env -f ~/foo.nix -i '.*'</screen> - -</para> - -<para>To copy the store path with symbolic name <literal>gcc</literal> -from another profile: - -<screen> -$ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc</screen> - -</para> - -<para>To install a specific store derivation (typically created by -<command>nix-instantiate</command>): - -<screen> -$ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv</screen> - -</para> - -<para>To install a specific output path: - -<screen> -$ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3</screen> - -</para> - -<para>To install from a Nix expression specified on the command-line: - -<screen> -$ nix-env -f ./foo.nix -i -E \ - 'f: (f {system = "i686-linux";}).subversionWithJava'</screen> - -I.e., this evaluates to <literal>(f: (f {system = -"i686-linux";}).subversionWithJava) (import ./foo.nix)</literal>, thus -selecting the <literal>subversionWithJava</literal> attribute from the -set returned by calling the function defined in -<filename>./foo.nix</filename>.</para> - -<para>A dry-run tells you which paths will be downloaded or built from -source: - -<screen> -$ nix-env -f '<nixpkgs>' -iA hello --dry-run -(dry run; not doing anything) -installing ‘hello-2.10’ -this path will be fetched (0.04 MiB download, 0.19 MiB unpacked): - /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10 - <replaceable>...</replaceable></screen> - -</para> - -<para>To install Firefox from the latest revision in the Nixpkgs/NixOS -14.12 channel: - -<screen> -$ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox -</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id="rsec-nix-env-upgrade"><title>Operation <option>--upgrade</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--upgrade</option></arg> - <arg choice='plain'><option>-u</option></arg> - </group> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-inst-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <group choice='opt'> - <arg choice='plain'><option>--lt</option></arg> - <arg choice='plain'><option>--leq</option></arg> - <arg choice='plain'><option>--eq</option></arg> - <arg choice='plain'><option>--always</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>args</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The upgrade operation creates a new user environment, based on -the current generation of the active profile, in which all store paths -are replaced for which there are newer versions in the set of paths -described by <replaceable>args</replaceable>. Paths for which there -are no newer versions are left untouched; this is not an error. It is -also not an error if an element of <replaceable>args</replaceable> -matches no installed derivations.</para> - -<para>For a description of how <replaceable>args</replaceable> is -mapped to a set of store paths, see <link -linkend="rsec-nix-env-install"><option>--install</option></link>. If -<replaceable>args</replaceable> describes multiple store paths with -the same symbolic name, only the one with the highest version is -installed.</para> - -</refsection> - -<refsection><title>Flags</title> - -<variablelist> - - <varlistentry><term><option>--lt</option></term> - - <listitem><para>Only upgrade a derivation to newer versions. This - is the default.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--leq</option></term> - - <listitem><para>In addition to upgrading to newer versions, also - “upgrade” to derivations that have the same version. Version are - not a unique identification of a derivation, so there may be many - derivations that have the same version. This flag may be useful - to force “synchronisation” between the installed and available - derivations.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--eq</option></term> - - <listitem><para><emphasis>Only</emphasis> “upgrade” to derivations - that have the same version. This may not seem very useful, but it - actually is, e.g., when there is a new release of Nixpkgs and you - want to replace installed applications with the same versions - built against newer dependencies (to reduce the number of - dependencies floating around on your system).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--always</option></term> - - <listitem><para>In addition to upgrading to newer versions, also - “upgrade” to derivations that have the same or a lower version. - I.e., derivations may actually be downgraded depending on what is - available in the active Nix expression.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>For the other flags, see <option -linkend="rsec-nix-env-install">--install</option>.</para> - -</refsection> - -<refsection><title>Examples</title> - -<screen> -$ nix-env --upgrade gcc -upgrading `gcc-3.3.1' to `gcc-3.4' - -$ nix-env -u gcc-3.3.2 --always <lineannotation>(switch to a specific version)</lineannotation> -upgrading `gcc-3.4' to `gcc-3.3.2' - -$ nix-env --upgrade pan -<lineannotation>(no upgrades available, so nothing happens)</lineannotation> - -$ nix-env -u <lineannotation>(try to upgrade everything)</lineannotation> -upgrading `hello-2.1.2' to `hello-2.1.3' -upgrading `mozilla-1.2' to `mozilla-1.4'</screen> - -</refsection> - -<refsection xml:id="ssec-version-comparisons"><title>Versions</title> - -<para>The upgrade operation determines whether a derivation -<varname>y</varname> is an upgrade of a derivation -<varname>x</varname> by looking at their respective -<literal>name</literal> attributes. The names (e.g., -<literal>gcc-3.3.1</literal> are split into two parts: the package -name (<literal>gcc</literal>), and the version -(<literal>3.3.1</literal>). The version part starts after the first -dash not followed by a letter. <varname>x</varname> is considered an -upgrade of <varname>y</varname> if their package names match, and the -version of <varname>y</varname> is higher that that of -<varname>x</varname>.</para> - -<para>The versions are compared by splitting them into contiguous -components of numbers and letters. E.g., <literal>3.3.1pre5</literal> -is split into <literal>[3, 3, 1, "pre", 5]</literal>. These lists are -then compared lexicographically (from left to right). Corresponding -components <varname>a</varname> and <varname>b</varname> are compared -as follows. If they are both numbers, integer comparison is used. If -<varname>a</varname> is an empty string and <varname>b</varname> is a -number, <varname>a</varname> is considered less than -<varname>b</varname>. The special string component -<literal>pre</literal> (for <emphasis>pre-release</emphasis>) is -considered to be less than other components. String components are -considered less than number components. Otherwise, they are compared -lexicographically (i.e., using case-sensitive string comparison).</para> - -<para>This is illustrated by the following examples: - -<screen> -1.0 < 2.3 -2.1 < 2.3 -2.3 = 2.3 -2.5 > 2.3 -3.1 > 2.3 -2.3.1 > 2.3 -2.3.1 > 2.3a -2.3pre1 < 2.3 -2.3pre3 < 2.3pre12 -2.3a < 2.3c -2.3pre1 < 2.3c -2.3pre1 < 2.3q</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--uninstall</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--uninstall</option></arg> - <arg choice='plain'><option>-e</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The uninstall operation creates a new user environment, based on -the current generation of the active profile, from which the store -paths designated by the symbolic names -<replaceable>names</replaceable> are removed.</para> - -</refsection> - -<refsection><title>Examples</title> - -<screen> -$ nix-env --uninstall gcc -$ nix-env -e '.*' <lineannotation>(remove everything)</lineannotation></screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id="rsec-nix-env-set"><title>Operation <option>--set</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--set</option></arg> - <arg choice='plain'><replaceable>drvname</replaceable></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The <option>--set</option> operation modifies the current generation of a -profile so that it contains exactly the specified derivation, and nothing else. -</para> - -</refsection> - -<refsection><title>Examples</title> - -<para> -The following updates a profile such that its current generation will contain -just Firefox: - -<screen> -$ nix-env -p /nix/var/nix/profiles/browser --set firefox</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id="rsec-nix-env-set-flag"><title>Operation <option>--set-flag</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--set-flag</option></arg> - <arg choice='plain'><replaceable>name</replaceable></arg> - <arg choice='plain'><replaceable>value</replaceable></arg> - <arg choice='plain' rep='repeat'><replaceable>drvnames</replaceable></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The <option>--set-flag</option> operation allows meta attributes -of installed packages to be modified. There are several attributes -that can be usefully modified, because they affect the behaviour of -<command>nix-env</command> or the user environment build -script: - -<itemizedlist> - - <listitem><para><varname>priority</varname> can be changed to - resolve filename clashes. The user environment build script uses - the <varname>meta.priority</varname> attribute of derivations to - resolve filename collisions between packages. Lower priority values - denote a higher priority. For instance, the GCC wrapper package and - the Binutils package in Nixpkgs both have a file - <filename>bin/ld</filename>, so previously if you tried to install - both you would get a collision. Now, on the other hand, the GCC - wrapper declares a higher priority than Binutils, so the former’s - <filename>bin/ld</filename> is symlinked in the user - environment.</para></listitem> - - <listitem><para><varname>keep</varname> can be set to - <literal>true</literal> to prevent the package from being upgraded - or replaced. This is useful if you want to hang on to an older - version of a package.</para></listitem> - - <listitem><para><varname>active</varname> can be set to - <literal>false</literal> to “disable” the package. That is, no - symlinks will be generated to the files of the package, but it - remains part of the profile (so it won’t be garbage-collected). It - can be set back to <literal>true</literal> to re-enable the - package.</para></listitem> - -</itemizedlist> - -</para> - -</refsection> - -<refsection><title>Examples</title> - -<para>To prevent the currently installed Firefox from being upgraded: - -<screen> -$ nix-env --set-flag keep true firefox</screen> - -After this, <command>nix-env -u</command> will ignore Firefox.</para> - -<para>To disable the currently installed Firefox, then install a new -Firefox while the old remains part of the profile: - -<screen> -$ nix-env -q -firefox-2.0.0.9 <lineannotation>(the current one)</lineannotation> - -$ nix-env --preserve-installed -i firefox-2.0.0.11 -installing `firefox-2.0.0.11' -building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment' -collision between `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.11/bin/firefox' - and `/nix/store/<replaceable>...</replaceable>-firefox-2.0.0.9/bin/firefox'. -<lineannotation>(i.e., can’t have two active at the same time)</lineannotation> - -$ nix-env --set-flag active false firefox -setting flag on `firefox-2.0.0.9' - -$ nix-env --preserve-installed -i firefox-2.0.0.11 -installing `firefox-2.0.0.11' - -$ nix-env -q -firefox-2.0.0.11 <lineannotation>(the enabled one)</lineannotation> -firefox-2.0.0.9 <lineannotation>(the disabled one)</lineannotation></screen> - -</para> - -<para>To make files from <literal>binutils</literal> take precedence -over files from <literal>gcc</literal>: - -<screen> -$ nix-env --set-flag priority 5 binutils -$ nix-env --set-flag priority 10 gcc</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--query</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--query</option></arg> - <arg choice='plain'><option>-q</option></arg> - </group> - <group choice='opt'> - <arg choice='plain'><option>--installed</option></arg> - <arg choice='plain'><option>--available</option></arg> - <arg choice='plain'><option>-a</option></arg> - </group> - - <sbr /> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--status</option></arg> - <arg choice='plain'><option>-s</option></arg> - </group> - </arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr-path</option></arg> - <arg choice='plain'><option>-P</option></arg> - </group> - </arg> - <arg><option>--no-name</option></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--compare-versions</option></arg> - <arg choice='plain'><option>-c</option></arg> - </group> - </arg> - <arg><option>--system</option></arg> - <arg><option>--drv-path</option></arg> - <arg><option>--out-path</option></arg> - <arg><option>--description</option></arg> - <arg><option>--meta</option></arg> - - <sbr /> - - <arg><option>--xml</option></arg> - <arg><option>--json</option></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--prebuilt-only</option></arg> - <arg choice='plain'><option>-b</option></arg> - </group> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - <replaceable>attribute-path</replaceable> - </arg> - - <sbr /> - - <arg choice='plain' rep='repeat'><replaceable>names</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>The query operation displays information about either the store -paths that are installed in the current generation of the active -profile (<option>--installed</option>), or the derivations that are -available for installation in the active Nix expression -(<option>--available</option>). It only prints information about -derivations whose symbolic name matches one of -<replaceable>names</replaceable>.</para> - -<para>The derivations are sorted by their <literal>name</literal> -attributes.</para> - -</refsection> - - -<refsection><title>Source selection</title> - -<para>The following flags specify the set of things on which the query -operates.</para> - -<variablelist> - - <varlistentry><term><option>--installed</option></term> - - <listitem><para>The query operates on the store paths that are - installed in the current generation of the active profile. This - is the default.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--available</option></term> - <term><option>-a</option></term> - - <listitem><para>The query operates on the derivations that are - available in the active Nix expression.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Queries</title> - -<para>The following flags specify what information to display about -the selected derivations. Multiple flags may be specified, in which -case the information is shown in the order given here. Note that the -name of the derivation is shown unless <option>--no-name</option> is -specified.</para> - -<!-- TODO: fix the terminology here; i.e., derivations, store paths, -user environment elements, etc. --> - -<variablelist> - - <varlistentry><term><option>--xml</option></term> - - <listitem><para>Print the result in an XML representation suitable - for automatic processing by other tools. The root element is - called <literal>items</literal>, which contains a - <literal>item</literal> element for each available or installed - derivation. The fields discussed below are all stored in - attributes of the <literal>item</literal> - elements.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--json</option></term> - - <listitem><para>Print the result in a JSON representation suitable - for automatic processing by other tools.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--prebuilt-only</option> / <option>-b</option></term> - - <listitem><para>Show only derivations for which a substitute is - registered, i.e., there is a pre-built binary available that can - be downloaded in lieu of building the derivation. Thus, this - shows all packages that probably can be installed - quickly.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--status</option></term> - <term><option>-s</option></term> - - <listitem><para>Print the <emphasis>status</emphasis> of the - derivation. The status consists of three characters. The first - is <literal>I</literal> or <literal>-</literal>, indicating - whether the derivation is currently installed in the current - generation of the active profile. This is by definition the case - for <option>--installed</option>, but not for - <option>--available</option>. The second is <literal>P</literal> - or <literal>-</literal>, indicating whether the derivation is - present on the system. This indicates whether installation of an - available derivation will require the derivation to be built. The - third is <literal>S</literal> or <literal>-</literal>, indicating - whether a substitute is available for the - derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--attr-path</option></term> - <term><option>-P</option></term> - - <listitem><para>Print the <emphasis>attribute path</emphasis> of - the derivation, which can be used to unambiguously select it using - the <link linkend="opt-attr"><option>--attr</option> option</link> - available in commands that install derivations like - <literal>nix-env --install</literal>. This option only works - together with <option>--available</option></para></listitem> - - </varlistentry> - - <varlistentry><term><option>--no-name</option></term> - - <listitem><para>Suppress printing of the <literal>name</literal> - attribute of each derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--compare-versions</option> / - <option>-c</option></term> - - <listitem><para>Compare installed versions to available versions, - or vice versa (if <option>--available</option> is given). This is - useful for quickly seeing whether upgrades for installed - packages are available in a Nix expression. A column is added - with the following meaning: - - <variablelist> - - <varlistentry><term><literal><</literal> <replaceable>version</replaceable></term> - - <listitem><para>A newer version of the package is available - or installed.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal>=</literal> <replaceable>version</replaceable></term> - - <listitem><para>At most the same version of the package is - available or installed.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal>></literal> <replaceable>version</replaceable></term> - - <listitem><para>Only older versions of the package are - available or installed.</para></listitem> - - </varlistentry> - - <varlistentry><term><literal>- ?</literal></term> - - <listitem><para>No version of the package is available or - installed.</para></listitem> - - </varlistentry> - - </variablelist> - - </para></listitem> - - </varlistentry> - - <varlistentry><term><option>--system</option></term> - - <listitem><para>Print the <literal>system</literal> attribute of - the derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--drv-path</option></term> - - <listitem><para>Print the path of the store - derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--out-path</option></term> - - <listitem><para>Print the output path of the - derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--description</option></term> - - <listitem><para>Print a short (one-line) description of the - derivation, if available. The description is taken from the - <literal>meta.description</literal> attribute of the - derivation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--meta</option></term> - - <listitem><para>Print all of the meta-attributes of the - derivation. This option is only available with - <option>--xml</option> or <option>--json</option>.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To show installed packages: - -<screen> -$ nix-env -q -bison-1.875c -docbook-xml-4.2 -firefox-1.0.4 -MPlayer-1.0pre7 -ORBit2-2.8.3 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show available packages: - -<screen> -$ nix-env -qa -firefox-1.0.7 -GConf-2.4.0.1 -MPlayer-1.0pre7 -ORBit2-2.8.3 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show the status of available packages: - -<screen> -$ nix-env -qas --P- firefox-1.0.7 <lineannotation>(not installed but present)</lineannotation> ---S GConf-2.4.0.1 <lineannotation>(not present, but there is a substitute for fast installation)</lineannotation> ---S MPlayer-1.0pre3 <lineannotation>(i.e., this is not the installed MPlayer, even though the version is the same!)</lineannotation> -IP- ORBit2-2.8.3 <lineannotation>(installed and by definition present)</lineannotation> -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show available packages in the Nix expression <filename>foo.nix</filename>: - -<screen> -$ nix-env -f ./foo.nix -qa -foo-1.2.3 -</screen> - -</para> - -<para>To compare installed versions to what’s available: - -<screen> -$ nix-env -qc -<replaceable>...</replaceable> -acrobat-reader-7.0 - ? <lineannotation>(package is not available at all)</lineannotation> -autoconf-2.59 = 2.59 <lineannotation>(same version)</lineannotation> -firefox-1.0.4 < 1.0.7 <lineannotation>(a more recent version is available)</lineannotation> -<replaceable>...</replaceable> -</screen> - -</para> - -<para>To show all packages with “<literal>zip</literal>” in the name: - -<screen> -$ nix-env -qa '.*zip.*' -bzip2-1.0.6 -gzip-1.6 -zip-3.0 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show all packages with “<literal>firefox</literal>” or -“<literal>chromium</literal>” in the name: - -<screen> -$ nix-env -qa '.*(firefox|chromium).*' -chromium-37.0.2062.94 -chromium-beta-38.0.2125.24 -firefox-32.0.3 -firefox-with-plugins-13.0.1 -<replaceable>…</replaceable> -</screen> - -</para> - -<para>To show all packages in the latest revision of the Nixpkgs -repository: - -<screen> -$ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa -</screen> - -</para> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--switch-profile</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--switch-profile</option></arg> - <arg choice='plain'><option>-S</option></arg> - </group> - <arg choice='req'><replaceable>path</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>This operation makes <replaceable>path</replaceable> the current -profile for the user. That is, the symlink -<filename>~/.nix-profile</filename> is made to point to -<replaceable>path</replaceable>.</para> - -</refsection> - -<refsection><title>Examples</title> - -<screen> -$ nix-env -S ~/my-profile</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--list-generations</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--list-generations</option></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>This operation print a list of all the currently existing -generations for the active profile. These may be switched to using -the <option>--switch-generation</option> operation. It also prints -the creation date of the generation, and indicates the current -generation.</para> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-env --list-generations - 95 2004-02-06 11:48:24 - 96 2004-02-06 11:49:01 - 97 2004-02-06 16:22:45 - 98 2004-02-06 16:24:33 (current)</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--delete-generations</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--delete-generations</option></arg> - <arg choice='plain' rep='repeat'><replaceable>generations</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>This operation deletes the specified generations of the current -profile. The generations can be a list of generation numbers, the -special value <literal>old</literal> to delete all non-current -generations, a value such as <literal>30d</literal> to delete all -generations older than the specified number of days (except for the -generation that was active at that point in time), or a value such as -<literal>+5</literal> to keep the last <literal>5</literal> generations -ignoring any newer than current, e.g., if <literal>30</literal> is the current -generation <literal>+5</literal> will delete generation <literal>25</literal> -and all older generations. -Periodically deleting old generations is important to make garbage collection -effective.</para> - -</refsection> - -<refsection><title>Examples</title> - -<screen> -$ nix-env --delete-generations 3 4 8 - -$ nix-env --delete-generations +5 - -$ nix-env --delete-generations 30d - -$ nix-env -p other_profile --delete-generations old</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--switch-generation</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <group choice='req'> - <arg choice='plain'><option>--switch-generation</option></arg> - <arg choice='plain'><option>-G</option></arg> - </group> - <arg choice='req'><replaceable>generation</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>This operation makes generation number -<replaceable>generation</replaceable> the current generation of the -active profile. That is, if the -<filename><replaceable>profile</replaceable></filename> is the path to -the active profile, then the symlink -<filename><replaceable>profile</replaceable></filename> is made to -point to -<filename><replaceable>profile</replaceable>-<replaceable>generation</replaceable>-link</filename>, -which is in turn a symlink to the actual user environment in the Nix -store.</para> - -<para>Switching will fail if the specified generation does not exist.</para> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-env -G 42 -switching from generation 50 to 42</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--rollback</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-env</command> - <arg choice='plain'><option>--rollback</option></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>This operation switches to the “previous” generation of the -active profile, that is, the highest numbered generation lower than -the current generation, if it exists. It is just a convenience -wrapper around <option>--list-generations</option> and -<option>--switch-generation</option>.</para> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-env --rollback -switching from generation 92 to 91 - -$ nix-env --rollback -error: no generation older than the current (91) exists</screen> - -</refsection> - -</refsection> - - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - - <varlistentry><term><envar>NIX_PROFILE</envar></term> - - <listitem><para>Location of the Nix profile. Defaults to the - target of the symlink <filename>~/.nix-profile</filename>, if it - exists, or <filename>/nix/var/nix/profiles/default</filename> - otherwise.</para></listitem> - - </varlistentry> - - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-hash.xml b/doc/manual/command-ref/nix-hash.xml deleted file mode 100644 index 80263e18e..000000000 --- a/doc/manual/command-ref/nix-hash.xml +++ /dev/null @@ -1,176 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-hash"> - -<refmeta> - <refentrytitle>nix-hash</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-hash</refname> - <refpurpose>compute the cryptographic hash of a path</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-hash</command> - <arg><option>--flat</option></arg> - <arg><option>--base32</option></arg> - <arg><option>--truncate</option></arg> - <arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg> - <arg choice='plain' rep='repeat'><replaceable>path</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>nix-hash</command> - <arg choice='plain'><option>--to-base16</option></arg> - <arg choice='plain' rep='repeat'><replaceable>hash</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>nix-hash</command> - <arg choice='plain'><option>--to-base32</option></arg> - <arg choice='plain' rep='repeat'><replaceable>hash</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The command <command>nix-hash</command> computes the -cryptographic hash of the contents of each -<replaceable>path</replaceable> and prints it on standard output. By -default, it computes an MD5 hash, but other hash algorithms are -available as well. The hash is printed in hexadecimal. To generate -the same hash as <command>nix-prefetch-url</command> you have to -specify multiple arguments, see below for an example.</para> - -<para>The hash is computed over a <emphasis>serialisation</emphasis> -of each path: a dump of the file system tree rooted at the path. This -allows directories and symlinks to be hashed as well as regular files. -The dump is in the <emphasis>NAR format</emphasis> produced by <link -linkend="refsec-nix-store-dump"><command>nix-store</command> -<option>--dump</option></link>. Thus, <literal>nix-hash -<replaceable>path</replaceable></literal> yields the same -cryptographic hash as <literal>nix-store --dump -<replaceable>path</replaceable> | md5sum</literal>.</para> - -</refsection> - - -<refsection><title>Options</title> - -<variablelist> - - <varlistentry><term><option>--flat</option></term> - - <listitem><para>Print the cryptographic hash of the contents of - each regular file <replaceable>path</replaceable>. That is, do - not compute the hash over the dump of - <replaceable>path</replaceable>. The result is identical to that - produced by the GNU commands <command>md5sum</command> and - <command>sha1sum</command>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--base32</option></term> - - <listitem><para>Print the hash in a base-32 representation rather - than hexadecimal. This base-32 representation is more compact and - can be used in Nix expressions (such as in calls to - <function>fetchurl</function>).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--truncate</option></term> - - <listitem><para>Truncate hashes longer than 160 bits (such as - SHA-256) to 160 bits.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term> - - <listitem><para>Use the specified cryptographic hash algorithm, - which can be one of <literal>md5</literal>, - <literal>sha1</literal>, and - <literal>sha256</literal>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--to-base16</option></term> - - <listitem><para>Don’t hash anything, but convert the base-32 hash - representation <replaceable>hash</replaceable> to - hexadecimal.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--to-base32</option></term> - - <listitem><para>Don’t hash anything, but convert the hexadecimal - hash representation <replaceable>hash</replaceable> to - base-32.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Computing the same hash as <command>nix-prefetch-url</command>: -<screen> -$ nix-prefetch-url file://<(echo test) -1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj -$ nix-hash --type sha256 --flat --base32 <(echo test) -1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj -</screen> -</para> - -<para>Computing hashes: - -<screen> -$ mkdir test -$ echo "hello" > test/world - -$ nix-hash test/ <lineannotation>(MD5 hash; default)</lineannotation> -8179d3caeff1869b5ba1744e5a245c04 - -$ nix-store --dump test/ | md5sum <lineannotation>(for comparison)</lineannotation> -8179d3caeff1869b5ba1744e5a245c04 - - -$ nix-hash --type sha1 test/ -e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 - -$ nix-hash --type sha1 --base32 test/ -nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 - -$ nix-hash --type sha256 --flat test/ -error: reading file `test/': Is a directory - -$ nix-hash --type sha256 --flat test/world -5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03</screen> - -</para> - -<para>Converting between hexadecimal and base-32: - -<screen> -$ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6 -nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 - -$ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4 -e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6</screen> - -</para> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml deleted file mode 100644 index 53f06aed1..000000000 --- a/doc/manual/command-ref/nix-instantiate.xml +++ /dev/null @@ -1,266 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-instantiate"> - -<refmeta> - <refentrytitle>nix-instantiate</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-instantiate</refname> - <refpurpose>instantiate store derivations from Nix expressions</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-instantiate</command> - <group> - <arg choice='plain'><option>--parse</option></arg> - <arg choice='plain'> - <option>--eval</option> - <arg><option>--strict</option></arg> - <arg><option>--json</option></arg> - <arg><option>--xml</option></arg> - </arg> - </group> - <arg><option>--read-write-mode</option></arg> - <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - <replaceable>attrPath</replaceable> - </arg> - <arg><option>--add-root</option> <replaceable>path</replaceable></arg> - <arg><option>--indirect</option></arg> - <group> - <arg choice='plain'><option>--expr</option></arg> - <arg choice='plain'><option>-E</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg> - </cmdsynopsis> - <cmdsynopsis> - <command>nix-instantiate</command> - <arg choice='plain'><option>--find-file</option></arg> - <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The command <command>nix-instantiate</command> generates <link -linkend="gloss-derivation">store derivations</link> from (high-level) -Nix expressions. It evaluates the Nix expressions in each of -<replaceable>files</replaceable> (which defaults to -<replaceable>./default.nix</replaceable>). Each top-level expression -should evaluate to a derivation, a list of derivations, or a set of -derivations. The paths of the resulting store derivations are printed -on standard output.</para> - -<para>If <replaceable>files</replaceable> is the character -<literal>-</literal>, then a Nix expression will be read from standard -input.</para> - -<para condition="manual">See also <xref linkend="sec-common-options" -/> for a list of common options.</para> - -</refsection> - - -<refsection><title>Options</title> - -<variablelist> - - <varlistentry> - <term><option>--add-root</option> <replaceable>path</replaceable></term> - <term><option>--indirect</option></term> - - <listitem><para>See the <link linkend="opt-add-root">corresponding - options</link> in <command>nix-store</command>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--parse</option></term> - - <listitem><para>Just parse the input files, and print their - abstract syntax trees on standard output in ATerm - format.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--eval</option></term> - - <listitem><para>Just parse and evaluate the input files, and print - the resulting values on standard output. No instantiation of - store derivations takes place.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--find-file</option></term> - - <listitem><para>Look up the given files in Nix’s search path (as - specified by the <envar linkend="env-NIX_PATH">NIX_PATH</envar> - environment variable). If found, print the corresponding absolute - paths on standard output. For instance, if - <envar>NIX_PATH</envar> is - <literal>nixpkgs=/home/alice/nixpkgs</literal>, then - <literal>nix-instantiate --find-file nixpkgs/default.nix</literal> - will print - <literal>/home/alice/nixpkgs/default.nix</literal>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--strict</option></term> - - <listitem><para>When used with <option>--eval</option>, - recursively evaluate list elements and attributes. Normally, such - sub-expressions are left unevaluated (since the Nix expression - language is lazy).</para> - - <warning><para>This option can cause non-termination, because lazy - data structures can be infinitely large.</para></warning> - - </listitem> - - </varlistentry> - - <varlistentry><term><option>--json</option></term> - - <listitem><para>When used with <option>--eval</option>, print the resulting - value as an JSON representation of the abstract syntax tree rather - than as an ATerm.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--xml</option></term> - - <listitem><para>When used with <option>--eval</option>, print the resulting - value as an XML representation of the abstract syntax tree rather than as - an ATerm. The schema is the same as that used by the <link - linkend="builtin-toXML"><function>toXML</function> built-in</link>. - </para></listitem> - - </varlistentry> - - <varlistentry><term><option>--read-write-mode</option></term> - - <listitem><para>When used with <option>--eval</option>, perform - evaluation in read/write mode so nix language features that - require it will still work (at the cost of needing to do - instantiation of every evaluated derivation). If this option is - not enabled, there may be uninstantiated store paths in the final - output.</para> - - </listitem> - - </varlistentry> - -</variablelist> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Instantiating store derivations from a Nix expression, and -building them using <command>nix-store</command>: - -<screen> -$ nix-instantiate test.nix <lineannotation>(instantiate)</lineannotation> -/nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv - -$ nix-store -r $(nix-instantiate test.nix) <lineannotation>(build)</lineannotation> -<replaceable>...</replaceable> -/nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 <lineannotation>(output path)</lineannotation> - -$ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 -dr-xr-xr-x 2 eelco users 4096 1970-01-01 01:00 lib -...</screen> - -</para> - -<para>You can also give a Nix expression on the command line: - -<screen> -$ nix-instantiate -E 'with import <nixpkgs> { }; hello' -/nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv -</screen> - -This is equivalent to: - -<screen> -$ nix-instantiate '<nixpkgs>' -A hello -</screen> - -</para> - -<para>Parsing and evaluating Nix expressions: - -<screen> -$ nix-instantiate --parse -E '1 + 2' -1 + 2 - -$ nix-instantiate --eval -E '1 + 2' -3 - -$ nix-instantiate --eval --xml -E '1 + 2' -<![CDATA[<?xml version='1.0' encoding='utf-8'?> -<expr> - <int value="3" /> -</expr>]]></screen> - -</para> - -<para>The difference between non-strict and strict evaluation: - -<screen> -$ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }' -<replaceable>...</replaceable><![CDATA[ - <attr name="x"> - <string value="foo" /> - </attr> - <attr name="y"> - <unevaluated /> - </attr>]]> -<replaceable>...</replaceable></screen> - -Note that <varname>y</varname> is left unevaluated (the XML -representation doesn’t attempt to show non-normal forms). - -<screen> -$ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }' -<replaceable>...</replaceable><![CDATA[ - <attr name="x"> - <string value="foo" /> - </attr> - <attr name="y"> - <string value="foo" /> - </attr>]]> -<replaceable>...</replaceable></screen> - -</para> - -</refsection> - - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-prefetch-url.xml b/doc/manual/command-ref/nix-prefetch-url.xml deleted file mode 100644 index 621ded72e..000000000 --- a/doc/manual/command-ref/nix-prefetch-url.xml +++ /dev/null @@ -1,131 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-prefetch-url"> - -<refmeta> - <refentrytitle>nix-prefetch-url</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-prefetch-url</refname> - <refpurpose>copy a file from a URL into the store and print its hash</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-prefetch-url</command> - <arg><option>--version</option></arg> - <arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg> - <arg><option>--print-path</option></arg> - <arg><option>--unpack</option></arg> - <arg><option>--name</option> <replaceable>name</replaceable></arg> - <arg choice='plain'><replaceable>url</replaceable></arg> - <arg><replaceable>hash</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>The command <command>nix-prefetch-url</command> downloads the -file referenced by the URL <replaceable>url</replaceable>, prints its -cryptographic hash, and copies it into the Nix store. The file name -in the store is -<filename><replaceable>hash</replaceable>-<replaceable>baseName</replaceable></filename>, -where <replaceable>baseName</replaceable> is everything following the -final slash in <replaceable>url</replaceable>.</para> - -<para>This command is just a convenience for Nix expression writers. -Often a Nix expression fetches some source distribution from the -network using the <literal>fetchurl</literal> expression contained in -Nixpkgs. However, <literal>fetchurl</literal> requires a -cryptographic hash. If you don't know the hash, you would have to -download the file first, and then <literal>fetchurl</literal> would -download it again when you build your Nix expression. Since -<literal>fetchurl</literal> uses the same name for the downloaded file -as <command>nix-prefetch-url</command>, the redundant download can be -avoided.</para> - -<para>If <replaceable>hash</replaceable> is specified, then a download -is not performed if the Nix store already contains a file with the -same hash and base name. Otherwise, the file is downloaded, and an -error is signaled if the actual hash of the file does not match the -specified hash.</para> - -<para>This command prints the hash on standard output. Additionally, -if the option <option>--print-path</option> is used, the path of the -downloaded file in the Nix store is also printed.</para> - -</refsection> - - -<refsection><title>Options</title> - -<variablelist> - - <varlistentry><term><option>--type</option> <replaceable>hashAlgo</replaceable></term> - - <listitem><para>Use the specified cryptographic hash algorithm, - which can be one of <literal>md5</literal>, - <literal>sha1</literal>, and - <literal>sha256</literal>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--print-path</option></term> - - <listitem><para>Print the store path of the downloaded file on - standard output.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--unpack</option></term> - - <listitem><para>Unpack the archive (which must be a tarball or zip - file) and add the result to the Nix store. The resulting hash can - be used with functions such as Nixpkgs’s - <varname>fetchzip</varname> or - <varname>fetchFromGitHub</varname>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--name</option> <replaceable>name</replaceable></term> - - <listitem><para>Override the name of the file in the Nix store. By - default, this is - <literal><replaceable>hash</replaceable>-<replaceable>basename</replaceable></literal>, - where <replaceable>basename</replaceable> is the last component of - <replaceable>url</replaceable>. Overriding the name is necessary - when <replaceable>basename</replaceable> contains characters that - are not allowed in Nix store paths.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<screen> -$ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz -0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i - -$ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz -0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i -/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz - -$ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz -079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7 -/nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz -</screen> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml deleted file mode 100644 index 2fef323c5..000000000 --- a/doc/manual/command-ref/nix-shell.xml +++ /dev/null @@ -1,411 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-shell"> - -<refmeta> - <refentrytitle>nix-shell</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-shell</refname> - <refpurpose>start an interactive shell based on a Nix expression</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-shell</command> - <arg><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></arg> - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - <replaceable>attrPath</replaceable> - </arg> - <arg><option>--command</option> <replaceable>cmd</replaceable></arg> - <arg><option>--run</option> <replaceable>cmd</replaceable></arg> - <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg> - <arg><option>--pure</option></arg> - <arg><option>--keep</option> <replaceable>name</replaceable></arg> - <group choice='req'> - <arg choice='plain'> - <group choice='req'> - <arg choice='plain'><option>--packages</option></arg> - <arg choice='plain'><option>-p</option></arg> - </group> - <arg choice='plain' rep='repeat'> - <group choice='req'> - <arg choice="plain"><replaceable>packages</replaceable></arg> - <arg choice="plain"><replaceable>expressions</replaceable></arg> - </group> - </arg> - </arg> - <arg><replaceable>path</replaceable></arg> - </group> - </cmdsynopsis> -</refsynopsisdiv> - -<refsection><title>Description</title> - -<para>The command <command>nix-shell</command> will build the -dependencies of the specified derivation, but not the derivation -itself. It will then start an interactive shell in which all -environment variables defined by the derivation -<replaceable>path</replaceable> have been set to their corresponding -values, and the script <literal>$stdenv/setup</literal> has been -sourced. This is useful for reproducing the environment of a -derivation for development.</para> - -<para>If <replaceable>path</replaceable> is not given, -<command>nix-shell</command> defaults to -<filename>shell.nix</filename> if it exists, and -<filename>default.nix</filename> otherwise.</para> - -<para>If <replaceable>path</replaceable> starts with -<literal>http://</literal> or <literal>https://</literal>, it is -interpreted as the URL of a tarball that will be downloaded and -unpacked to a temporary location. The tarball must include a single -top-level directory containing at least a file named -<filename>default.nix</filename>.</para> - -<para>If the derivation defines the variable -<varname>shellHook</varname>, it will be evaluated after -<literal>$stdenv/setup</literal> has been sourced. Since this hook is -not executed by regular Nix builds, it allows you to perform -initialisation specific to <command>nix-shell</command>. For example, -the derivation attribute - -<programlisting> -shellHook = - '' - echo "Hello shell" - ''; -</programlisting> - -will cause <command>nix-shell</command> to print <literal>Hello shell</literal>.</para> - -</refsection> - - -<refsection><title>Options</title> - -<para>All options not listed here are passed to <command>nix-store ---realise</command>, except for <option>--arg</option> and -<option>--attr</option> / <option>-A</option> which are passed to -<command>nix-instantiate</command>. <phrase condition="manual">See -also <xref linkend="sec-common-options" />.</phrase></para> - -<variablelist> - - <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term> - - <listitem><para>In the environment of the derivation, run the - shell command <replaceable>cmd</replaceable>. This command is - executed in an interactive shell. (Use <option>--run</option> to - use a non-interactive shell instead.) However, a call to - <literal>exit</literal> is implicitly added to the command, so the - shell will exit after running the command. To prevent this, add - <literal>return</literal> at the end; e.g. <literal>--command - "echo Hello; return"</literal> will print <literal>Hello</literal> - and then drop you into the interactive shell. This can be useful - for doing any additional initialisation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--run</option> <replaceable>cmd</replaceable></term> - - <listitem><para>Like <option>--command</option>, but executes the - command in a non-interactive shell. This means (among other - things) that if you hit Ctrl-C while the command is running, the - shell exits.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--exclude</option> <replaceable>regexp</replaceable></term> - - <listitem><para>Do not build any dependencies whose store path - matches the regular expression <replaceable>regexp</replaceable>. - This option may be specified multiple times.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--pure</option></term> - - <listitem><para>If this flag is specified, the environment is - almost entirely cleared before the interactive shell is started, - so you get an environment that more closely corresponds to the - “real” Nix build. A few variables, in particular - <envar>HOME</envar>, <envar>USER</envar> and - <envar>DISPLAY</envar>, are retained. Note that - <filename>~/.bashrc</filename> and (depending on your Bash - installation) <filename>/etc/bashrc</filename> are still sourced, - so any variables set there will affect the interactive - shell.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--packages</option> / <option>-p</option> <replaceable>packages</replaceable>…</term> - - <listitem><para>Set up an environment in which the specified - packages are present. The command line arguments are interpreted - as attribute names inside the Nix Packages collection. Thus, - <literal>nix-shell -p libjpeg openjdk</literal> will start a shell - in which the packages denoted by the attribute names - <varname>libjpeg</varname> and <varname>openjdk</varname> are - present.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>-i</option> <replaceable>interpreter</replaceable></term> - - <listitem><para>The chained script interpreter to be invoked by - <command>nix-shell</command>. Only applicable in - <literal>#!</literal>-scripts (described <link - linkend="ssec-nix-shell-shebang">below</link>).</para> - - </listitem></varlistentry> - - <varlistentry><term><option>--keep</option> <replaceable>name</replaceable></term> - - <listitem><para>When a <option>--pure</option> shell is started, - keep the listed environment variables.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>The following common options are supported:</para> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - -<refsection><title>Environment variables</title> - -<variablelist> - - <varlistentry><term><envar>NIX_BUILD_SHELL</envar></term> - - <listitem><para>Shell used to start the interactive environment. - Defaults to the <command>bash</command> found in <envar>PATH</envar>.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To build the dependencies of the package Pan, and start an -interactive shell in which to build it: - -<screen> -$ nix-shell '<nixpkgs>' -A pan -[nix-shell]$ unpackPhase -[nix-shell]$ cd pan-* -[nix-shell]$ configurePhase -[nix-shell]$ buildPhase -[nix-shell]$ ./pan/gui/pan -</screen> - -To clear the environment first, and do some additional automatic -initialisation of the interactive shell: - -<screen> -$ nix-shell '<nixpkgs>' -A pan --pure \ - --command 'export NIX_DEBUG=1; export NIX_CORES=8; return' -</screen> - -Nix expressions can also be given on the command line using the -<command>-E</command> and <command>-p</command> flags. -For instance, the following starts a shell containing the packages -<literal>sqlite</literal> and <literal>libX11</literal>: - -<screen> -$ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""' -</screen> - -A shorter way to do the same is: - -<screen> -$ nix-shell -p sqlite xorg.libX11 -[nix-shell]$ echo $NIX_LDFLAGS -… -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib … -</screen> - -Note that <command>-p</command> accepts multiple full nix expressions that -are valid in the <literal>buildInputs = [ ... ]</literal> shown above, -not only package names. So the following is also legal: - -<screen> -$ nix-shell -p sqlite 'git.override { withManual = false; }' -</screen> - -The <command>-p</command> flag looks up Nixpkgs in the Nix search -path. You can override it by passing <option>-I</option> or setting -<envar>NIX_PATH</envar>. For example, the following gives you a shell -containing the Pan package from a specific revision of Nixpkgs: - -<screen> -$ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz - -[nix-shell:~]$ pan --version -Pan 0.139 -</screen> - -</para> - -</refsection> - - -<refsection xml:id="ssec-nix-shell-shebang"><title>Use as a <literal>#!</literal>-interpreter</title> - -<para>You can use <command>nix-shell</command> as a script interpreter -to allow scripts written in arbitrary languages to obtain their own -dependencies via Nix. This is done by starting the script with the -following lines: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell -i <replaceable>real-interpreter</replaceable> -p <replaceable>packages</replaceable> -</programlisting> - -where <replaceable>real-interpreter</replaceable> is the “real” script -interpreter that will be invoked by <command>nix-shell</command> after -it has obtained the dependencies and initialised the environment, and -<replaceable>packages</replaceable> are the attribute names of the -dependencies in Nixpkgs.</para> - -<para>The lines starting with <literal>#! nix-shell</literal> specify -<command>nix-shell</command> options (see above). Note that you cannot -write <literal>#! /usr/bin/env nix-shell -i ...</literal> because -many operating systems only allow one argument in -<literal>#!</literal> lines.</para> - -<para>For example, here is a Python script that depends on Python and -the <literal>prettytable</literal> package: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell -i python -p python pythonPackages.prettytable - -import prettytable - -# Print a simple table. -t = prettytable.PrettyTable(["N", "N^2"]) -for n in range(1, 10): t.add_row([n, n * n]) -print t -</programlisting> - -</para> - -<para>Similarly, the following is a Perl script that specifies that it -requires Perl and the <literal>HTML::TokeParser::Simple</literal> and -<literal>LWP</literal> packages: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP - -use HTML::TokeParser::Simple; - -# Fetch nixos.org and print all hrefs. -my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/'); - -while (my $token = $p->get_tag("a")) { - my $href = $token->get_attr("href"); - print "$href\n" if $href; -} -</programlisting> - -</para> - -<para>Sometimes you need to pass a simple Nix expression to customize -a package like Terraform: - -<programlisting><![CDATA[ -#! /usr/bin/env nix-shell -#! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])" - -terraform apply -]]></programlisting> - -<note><para>You must use double quotes (<literal>"</literal>) when -passing a simple Nix expression in a nix-shell shebang.</para></note> -</para> - -<para>Finally, using the merging of multiple nix-shell shebangs the -following Haskell script uses a specific branch of Nixpkgs/NixOS (the -18.03 stable branch): - -<programlisting><![CDATA[ -#! /usr/bin/env nix-shell -#! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])" -#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-18.03.tar.gz - -import Network.HTTP -import Text.HTML.TagSoup - --- Fetch nixos.org and print all hrefs. -main = do - resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/") - body <- getResponseBody resp - let tags = filter (isTagOpenName "a") $ parseTags body - let tags' = map (fromAttrib "href") tags - mapM_ putStrLn $ filter (/= "") tags' -]]></programlisting> - -If you want to be even more precise, you can specify a specific -revision of Nixpkgs: - -<programlisting> -#! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz -</programlisting> - -</para> - -<para>The examples above all used <option>-p</option> to get -dependencies from Nixpkgs. You can also use a Nix expression to build -your own dependencies. For example, the Python example could have been -written as: - -<programlisting> -#! /usr/bin/env nix-shell -#! nix-shell deps.nix -i python -</programlisting> - -where the file <filename>deps.nix</filename> in the same directory -as the <literal>#!</literal>-script contains: - -<programlisting> -with import <nixpkgs> {}; - -runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } "" -</programlisting> - -</para> - -</refsection> - - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/nix-store.xml b/doc/manual/command-ref/nix-store.xml deleted file mode 100644 index d71f9d8e4..000000000 --- a/doc/manual/command-ref/nix-store.xml +++ /dev/null @@ -1,1516 +0,0 @@ -<refentry xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="sec-nix-store"> - -<refmeta> - <refentrytitle>nix-store</refentrytitle> - <manvolnum>1</manvolnum> - <refmiscinfo class="source">Nix</refmiscinfo> - <refmiscinfo class="version"><xi:include href="../version.txt" parse="text"/></refmiscinfo> -</refmeta> - -<refnamediv> - <refname>nix-store</refname> - <refpurpose>manipulate or query the Nix store</refpurpose> -</refnamediv> - -<refsynopsisdiv> - <cmdsynopsis> - <command>nix-store</command> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="opt-common-syn.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(/db:nop/*)" /> - <arg><option>--add-root</option> <replaceable>path</replaceable></arg> - <arg><option>--indirect</option></arg> - <arg choice='plain'><replaceable>operation</replaceable></arg> - <arg rep='repeat'><replaceable>options</replaceable></arg> - <arg rep='repeat'><replaceable>arguments</replaceable></arg> - </cmdsynopsis> -</refsynopsisdiv> - - -<refsection><title>Description</title> - -<para>The command <command>nix-store</command> performs primitive -operations on the Nix store. You generally do not need to run this -command manually.</para> - -<para><command>nix-store</command> takes exactly one -<emphasis>operation</emphasis> flag which indicates the subcommand to -be performed. These are documented below.</para> - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Common options</title> - -<para>This section lists the options that are common to all -operations. These options are allowed for every subcommand, though -they may not always have an effect. <phrase condition="manual">See -also <xref linkend="sec-common-options" /> for a list of common -options.</phrase></para> - -<variablelist> - - <varlistentry xml:id="opt-add-root"><term><option>--add-root</option> <replaceable>path</replaceable></term> - - <listitem><para>Causes the result of a realisation - (<option>--realise</option> and <option>--force-realise</option>) - to be registered as a root of the garbage collector<phrase - condition="manual"> (see <xref linkend="ssec-gc-roots" - />)</phrase>. The root is stored in - <replaceable>path</replaceable>, which must be inside a directory - that is scanned for roots by the garbage collector (i.e., - typically in a subdirectory of - <filename>/nix/var/nix/gcroots/</filename>) - <emphasis>unless</emphasis> the <option>--indirect</option> flag - is used.</para> - - <para>If there are multiple results, then multiple symlinks will - be created by sequentially numbering symlinks beyond the first one - (e.g., <filename>foo</filename>, <filename>foo-2</filename>, - <filename>foo-3</filename>, and so on).</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--indirect</option></term> - - <listitem> - - <para>In conjunction with <option>--add-root</option>, this option - allows roots to be stored <emphasis>outside</emphasis> of the GC - roots directory. This is useful for commands such as - <command>nix-build</command> that place a symlink to the build - result in the current directory; such a build result should not be - garbage-collected unless the symlink is removed.</para> - - <para>The <option>--indirect</option> flag causes a uniquely named - symlink to <replaceable>path</replaceable> to be stored in - <filename>/nix/var/nix/gcroots/auto/</filename>. For instance, - - <screen> -$ nix-store --add-root /home/eelco/bla/result --indirect -r <replaceable>...</replaceable> - -$ ls -l /nix/var/nix/gcroots/auto -lrwxrwxrwx 1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result - -$ ls -l /home/eelco/bla/result -lrwxrwxrwx 1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10</screen> - - Thus, when <filename>/home/eelco/bla/result</filename> is removed, - the GC root in the <filename>auto</filename> directory becomes a - dangling symlink and will be ignored by the collector.</para> - - <warning><para>Note that it is not possible to move or rename - indirect GC roots, since the symlink in the - <filename>auto</filename> directory will still point to the old - location.</para></warning> - - </listitem> - - </varlistentry> - -</variablelist> - -<variablelist condition="manpage"> - <xi:include href="opt-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='opt-common']/*)" /> -</variablelist> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='rsec-nix-store-realise'><title>Operation <option>--realise</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <group choice='req'> - <arg choice='plain'><option>--realise</option></arg> - <arg choice='plain'><option>-r</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - <arg><option>--dry-run</option></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--realise</option> essentially “builds” -the specified store paths. Realisation is a somewhat overloaded term: - -<itemizedlist> - - <listitem><para>If the store path is a - <emphasis>derivation</emphasis>, realisation ensures that the output - paths of the derivation are <link - linkend="gloss-validity">valid</link> (i.e., the output path and its - closure exist in the file system). This can be done in several - ways. First, it is possible that the outputs are already valid, in - which case we are done immediately. Otherwise, there may be <link - linkend="gloss-substitute">substitutes</link> that produce the - outputs (e.g., by downloading them). Finally, the outputs can be - produced by performing the build action described by the - derivation.</para></listitem> - - <listitem><para>If the store path is not a derivation, realisation - ensures that the specified path is valid (i.e., it and its closure - exist in the file system). If the path is already valid, we are - done immediately. Otherwise, the path and any missing paths in its - closure may be produced through substitutes. If there are no - (successful) subsitutes, realisation fails.</para></listitem> - -</itemizedlist> - -</para> - -<para>The output path of each derivation is printed on standard -output. (For non-derivations argument, the argument itself is -printed.)</para> - -<para>The following flags are available:</para> - -<variablelist> - - <varlistentry><term><option>--dry-run</option></term> - - <listitem><para>Print on standard error a description of what - packages would be built or downloaded, without actually performing - the operation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--ignore-unknown</option></term> - - <listitem><para>If a non-derivation path does not have a - substitute, then silently ignore it.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--check</option></term> - - <listitem><para>This option allows you to check whether a - derivation is deterministic. It rebuilds the specified derivation - and checks whether the result is bitwise-identical with the - existing outputs, printing an error if that’s not the case. The - outputs of the specified derivation must already exist. When used - with <option>-K</option>, if an output path is not identical to - the corresponding output from the previous build, the new output - path is left in - <filename>/nix/store/<replaceable>name</replaceable>.check.</filename></para> - - <para>See also the <option>build-repeat</option> configuration - option, which repeats a derivation a number of times and prevents - its outputs from being registered as “valid” in the Nix store - unless they are identical.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>Special exit codes:</para> - -<variablelist> - - <varlistentry><term><literal>100</literal></term> - <listitem><para>Generic build failure, the builder process - returned with a non-zero exit code.</para></listitem> - </varlistentry> - - <varlistentry><term><literal>101</literal></term> - <listitem><para>Build timeout, the build was aborted because it - did not complete within the specified <link - linkend='conf-timeout'><literal>timeout</literal></link>. - </para></listitem> - </varlistentry> - - <varlistentry><term><literal>102</literal></term> - <listitem><para>Hash mismatch, the build output was rejected - because it does not match the specified <link - linkend="fixed-output-drvs"><varname>outputHash</varname></link>. - </para></listitem> - </varlistentry> - - <varlistentry><term><literal>104</literal></term> - <listitem><para>Not deterministic, the build succeeded in check - mode but the resulting output is not binary reproducable.</para> - </listitem> - </varlistentry> - -</variablelist> - -<para>With the <option>--keep-going</option> flag it's possible for -multiple failures to occur, in this case the 1xx status codes are or combined -using binary or. <screen> -1100100 - ^^^^ - |||`- timeout - ||`-- output hash mismatch - |`--- build failure - `---- not deterministic -</screen></para> - -</refsection> - - -<refsection><title>Examples</title> - -<para>This operation is typically used to build store derivations -produced by <link -linkend="sec-nix-instantiate"><command>nix-instantiate</command></link>: - -<screen> -$ nix-store -r $(nix-instantiate ./test.nix) -/nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1</screen> - -This is essentially what <link -linkend="sec-nix-build"><command>nix-build</command></link> does.</para> - -<para>To test whether a previously-built derivation is deterministic: - -<screen> -$ nix-build '<nixpkgs>' -A hello --check -K -</screen> - -</para> - -</refsection> - - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='rsec-nix-store-serve'><title>Operation <option>--serve</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--serve</option></arg> - <arg><option>--write</option></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--serve</option> provides access to -the Nix store over stdin and stdout, and is intended to be used -as a means of providing Nix store access to a restricted ssh user. -</para> - -<para>The following flags are available:</para> - -<variablelist> - - <varlistentry><term><option>--write</option></term> - - <listitem><para>Allow the connected client to request the realization - of derivations. In effect, this can be used to make the host act - as a remote builder.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To turn a host into a build server, the -<filename>authorized_keys</filename> file can be used to provide build -access to a given SSH public key: - -<screen> -$ cat <<EOF >>/root/.ssh/authorized_keys -command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA... -EOF -</screen> - -</para> - -</refsection> - - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='rsec-nix-store-gc'><title>Operation <option>--gc</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--gc</option></arg> - <group> - <arg choice='plain'><option>--print-roots</option></arg> - <arg choice='plain'><option>--print-live</option></arg> - <arg choice='plain'><option>--print-dead</option></arg> - </group> - <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>Without additional flags, the operation <option>--gc</option> -performs a garbage collection on the Nix store. That is, all paths in -the Nix store not reachable via file system references from a set of -“roots”, are deleted.</para> - -<para>The following suboperations may be specified:</para> - -<variablelist> - - <varlistentry><term><option>--print-roots</option></term> - - <listitem><para>This operation prints on standard output the set - of roots used by the garbage collector. What constitutes a root - is described in <xref linkend="ssec-gc-roots" - />.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--print-live</option></term> - - <listitem><para>This operation prints on standard output the set - of “live” store paths, which are all the store paths reachable - from the roots. Live paths should never be deleted, since that - would break consistency — it would become possible that - applications are installed that reference things that are no - longer present in the store.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--print-dead</option></term> - - <listitem><para>This operation prints out on standard output the - set of “dead” store paths, which is just the opposite of the set - of live paths: any path in the store that is not live (with - respect to the roots) is dead.</para></listitem> - - </varlistentry> - -</variablelist> - -<para>By default, all unreachable paths are deleted. The following -options control what gets deleted and in what order: - -<variablelist> - - <varlistentry><term><option>--max-freed</option> <replaceable>bytes</replaceable></term> - - <listitem><para>Keep deleting paths until at least - <replaceable>bytes</replaceable> bytes have been deleted, then - stop. The argument <replaceable>bytes</replaceable> can be - followed by the multiplicative suffix <literal>K</literal>, - <literal>M</literal>, <literal>G</literal> or - <literal>T</literal>, denoting KiB, MiB, GiB or TiB - units.</para></listitem> - - </varlistentry> - -</variablelist> - -</para> - -<para>The behaviour of the collector is also influenced by the <link -linkend="conf-keep-outputs"><literal>keep-outputs</literal></link> -and <link -linkend="conf-keep-derivations"><literal>keep-derivations</literal></link> -variables in the Nix configuration file.</para> - -<para>By default, the collector prints the total number of freed bytes -when it finishes (or when it is interrupted). With -<option>--print-dead</option>, it prints the number of bytes that would -be freed.</para> - -</refsection> - - -<refsection><title>Examples</title> - -<para>To delete all unreachable paths, just do: - -<screen> -$ nix-store --gc -deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv' -<replaceable>...</replaceable> -8825586 bytes freed (8.42 MiB)</screen> - -</para> - -<para>To delete at least 100 MiBs of unreachable paths: - -<screen> -$ nix-store --gc --max-freed $((100 * 1024 * 1024))</screen> - -</para> - -</refsection> - - -</refsection> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--delete</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--delete</option></arg> - <arg><option>--ignore-liveness</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--delete</option> deletes the store paths -<replaceable>paths</replaceable> from the Nix store, but only if it is -safe to do so; that is, when the path is not reachable from a root of -the garbage collector. This means that you can only delete paths that -would also be deleted by <literal>nix-store --gc</literal>. Thus, -<literal>--delete</literal> is a more targeted version of -<literal>--gc</literal>.</para> - -<para>With the option <option>--ignore-liveness</option>, reachability -from the roots is ignored. However, the path still won’t be deleted -if there are other paths in the store that refer to it (i.e., depend -on it).</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --delete /nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4 -0 bytes freed (0.00 MiB) -error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' since it is still alive</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-query'><title>Operation <option>--query</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <group choice='req'> - <arg choice='plain'><option>--query</option></arg> - <arg choice='plain'><option>-q</option></arg> - </group> - <group choice='req'> - <arg choice='plain'><option>--outputs</option></arg> - <arg choice='plain'><option>--requisites</option></arg> - <arg choice='plain'><option>-R</option></arg> - <arg choice='plain'><option>--references</option></arg> - <arg choice='plain'><option>--referrers</option></arg> - <arg choice='plain'><option>--referrers-closure</option></arg> - <arg choice='plain'><option>--deriver</option></arg> - <arg choice='plain'><option>-d</option></arg> - <arg choice='plain'><option>--graph</option></arg> - <arg choice='plain'><option>--tree</option></arg> - <arg choice='plain'><option>--binding</option> <replaceable>name</replaceable></arg> - <arg choice='plain'><option>-b</option> <replaceable>name</replaceable></arg> - <arg choice='plain'><option>--hash</option></arg> - <arg choice='plain'><option>--size</option></arg> - <arg choice='plain'><option>--roots</option></arg> - </group> - <arg><option>--use-output</option></arg> - <arg><option>-u</option></arg> - <arg><option>--force-realise</option></arg> - <arg><option>-f</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> -</cmdsynopsis> - -</refsection> - - -<refsection><title>Description</title> - -<para>The operation <option>--query</option> displays various bits of -information about the store paths . The queries are described below. At -most one query can be specified. The default query is -<option>--outputs</option>.</para> - -<para>The paths <replaceable>paths</replaceable> may also be symlinks -from outside of the Nix store, to the Nix store. In that case, the -query is applied to the target of the symlink.</para> - - -</refsection> - - -<refsection><title>Common query options</title> - -<variablelist> - - <varlistentry><term><option>--use-output</option></term> - <term><option>-u</option></term> - - <listitem><para>For each argument to the query that is a store - derivation, apply the query to the output path of the derivation - instead.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--force-realise</option></term> - <term><option>-f</option></term> - - <listitem><para>Realise each argument to the query first (see - <link linkend="rsec-nix-store-realise"><command>nix-store - --realise</command></link>).</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection xml:id='nixref-queries'><title>Queries</title> - -<variablelist> - - <varlistentry><term><option>--outputs</option></term> - - <listitem><para>Prints out the <link - linkend="gloss-output-path">output paths</link> of the store - derivations <replaceable>paths</replaceable>. These are the paths - that will be produced when the derivation is - built.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--requisites</option></term> - <term><option>-R</option></term> - - <listitem><para>Prints out the <link - linkend="gloss-closure">closure</link> of the store path - <replaceable>paths</replaceable>.</para> - - <para>This query has one option:</para> - - <variablelist> - - <varlistentry><term><option>--include-outputs</option></term> - - <listitem><para>Also include the output path of store - derivations, and their closures.</para></listitem> - - </varlistentry> - - </variablelist> - - <para>This query can be used to implement various kinds of - deployment. A <emphasis>source deployment</emphasis> is obtained - by distributing the closure of a store derivation. A - <emphasis>binary deployment</emphasis> is obtained by distributing - the closure of an output path. A <emphasis>cache - deployment</emphasis> (combined source/binary deployment, - including binaries of build-time-only dependencies) is obtained by - distributing the closure of a store derivation and specifying the - option <option>--include-outputs</option>.</para> - - </listitem> - - </varlistentry> - - <varlistentry><term><option>--references</option></term> - - <listitem><para>Prints the set of <link - linkend="gloss-reference">references</link> of the store paths - <replaceable>paths</replaceable>, that is, their immediate - dependencies. (For <emphasis>all</emphasis> dependencies, use - <option>--requisites</option>.)</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--referrers</option></term> - - <listitem><para>Prints the set of <emphasis>referrers</emphasis> of - the store paths <replaceable>paths</replaceable>, that is, the - store paths currently existing in the Nix store that refer to one - of <replaceable>paths</replaceable>. Note that contrary to the - references, the set of referrers is not constant; it can change as - store paths are added or removed.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--referrers-closure</option></term> - - <listitem><para>Prints the closure of the set of store paths - <replaceable>paths</replaceable> under the referrers relation; that - is, all store paths that directly or indirectly refer to one of - <replaceable>paths</replaceable>. These are all the path currently - in the Nix store that are dependent on - <replaceable>paths</replaceable>.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--deriver</option></term> - <term><option>-d</option></term> - - <listitem><para>Prints the <link - linkend="gloss-deriver">deriver</link> of the store paths - <replaceable>paths</replaceable>. If the path has no deriver - (e.g., if it is a source file), or if the deriver is not known - (e.g., in the case of a binary-only deployment), the string - <literal>unknown-deriver</literal> is printed.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--graph</option></term> - - <listitem><para>Prints the references graph of the store paths - <replaceable>paths</replaceable> in the format of the - <command>dot</command> tool of AT&T's <link - xlink:href="http://www.graphviz.org/">Graphviz package</link>. - This can be used to visualise dependency graphs. To obtain a - build-time dependency graph, apply this to a store derivation. To - obtain a runtime dependency graph, apply it to an output - path.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--tree</option></term> - - <listitem><para>Prints the references graph of the store paths - <replaceable>paths</replaceable> as a nested ASCII tree. - References are ordered by descending closure size; this tends to - flatten the tree, making it more readable. The query only - recurses into a store path when it is first encountered; this - prevents a blowup of the tree representation of the - graph.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--graphml</option></term> - - <listitem><para>Prints the references graph of the store paths - <replaceable>paths</replaceable> in the <link - xlink:href="http://graphml.graphdrawing.org/">GraphML</link> file format. - This can be used to visualise dependency graphs. To obtain a - build-time dependency graph, apply this to a store derivation. To - obtain a runtime dependency graph, apply it to an output - path.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--binding</option> <replaceable>name</replaceable></term> - <term><option>-b</option> <replaceable>name</replaceable></term> - - <listitem><para>Prints the value of the attribute - <replaceable>name</replaceable> (i.e., environment variable) of - the store derivations <replaceable>paths</replaceable>. It is an - error for a derivation to not have the specified - attribute.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--hash</option></term> - - <listitem><para>Prints the SHA-256 hash of the contents of the - store paths <replaceable>paths</replaceable> (that is, the hash of - the output of <command>nix-store --dump</command> on the given - paths). Since the hash is stored in the Nix database, this is a - fast operation.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--size</option></term> - - <listitem><para>Prints the size in bytes of the contents of the - store paths <replaceable>paths</replaceable> — to be precise, the - size of the output of <command>nix-store --dump</command> on the - given paths. Note that the actual disk space required by the - store paths may be higher, especially on filesystems with large - cluster sizes.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--roots</option></term> - - <listitem><para>Prints the garbage collector roots that point, - directly or indirectly, at the store paths - <replaceable>paths</replaceable>.</para></listitem> - - </varlistentry> - -</variablelist> - -</refsection> - - -<refsection><title>Examples</title> - -<para>Print the closure (runtime dependencies) of the -<command>svn</command> program in the current user environment: - -<screen> -$ nix-store -qR $(which svn) -/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 -/nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4 -<replaceable>...</replaceable></screen> - -</para> - -<para>Print the build-time dependencies of <command>svn</command>: - -<screen> -$ nix-store -qR $(nix-store -qd $(which svn)) -/nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv -/nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh -/nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv -<replaceable>... lots of other paths ...</replaceable></screen> - -The difference with the previous example is that we ask the closure of -the derivation (<option>-qd</option>), not the closure of the output -path that contains <command>svn</command>.</para> - -<para>Show the build-time dependencies as a tree: - -<screen> -$ nix-store -q --tree $(nix-store -qd $(which svn)) -/nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv -+---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh -+---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv -| +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash -| +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh -<replaceable>...</replaceable></screen> - -</para> - -<para>Show all paths that depend on the same OpenSSL library as -<command>svn</command>: - -<screen> -$ nix-store -q --referrers $(nix-store -q --binding openssl $(nix-store -qd $(which svn))) -/nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0 -/nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4 -/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3 -/nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5</screen> - -</para> - -<para>Show all paths that directly or indirectly depend on the Glibc -(C library) used by <command>svn</command>: - -<screen> -$ nix-store -q --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}') -/nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2 -/nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4 -<replaceable>...</replaceable></screen> - -Note that <command>ldd</command> is a command that prints out the -dynamic libraries used by an ELF executable.</para> - -<para>Make a picture of the runtime dependency graph of the current -user environment: - -<screen> -$ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps -$ gv graph.ps</screen> - -</para> - -<para>Show every garbage collector root that points to a store path -that depends on <command>svn</command>: - -<screen> -$ nix-store -q --roots $(which svn) -/nix/var/nix/profiles/default-81-link -/nix/var/nix/profiles/default-82-link -/nix/var/nix/profiles/per-user/eelco/profile-97-link -</screen> - -</para> - -</refsection> - - -</refsection> - - - -<!--######################################################################--> - -<!-- -<refsection xml:id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>-XXX-register-validity</option></arg> -</cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>TODO</para> - -</refsection> - -</refsection> ---> - - - -<!--######################################################################--> - -<refsection><title>Operation <option>--add</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--add</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--add</option> adds the specified paths to -the Nix store. It prints the resulting paths in the Nix store on -standard output.</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --add ./foo.c -/nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c</screen> - -</refsection> - -</refsection> - -<!--######################################################################--> - -<refsection><title>Operation <option>--add-fixed</option></title> - -<refsection><title>Synopsis</title> - -<cmdsynopsis> - <command>nix-store</command> - <arg><option>--recursive</option></arg> - <arg choice='plain'><option>--add-fixed</option></arg> - <arg choice='plain'><replaceable>algorithm</replaceable></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> -</cmdsynopsis> - -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--add-fixed</option> adds the specified paths to -the Nix store. Unlike <option>--add</option> paths are registered using the -specified hashing algorithm, resulting in the same output path as a fixed-output -derivation. This can be used for sources that are not available from a public -url or broke since the download expression was written. -</para> - -<para>This operation has the following options: - -<variablelist> - - <varlistentry><term><option>--recursive</option></term> - - <listitem><para> - Use recursive instead of flat hashing mode, used when adding directories - to the store. - </para></listitem> - - </varlistentry> - -</variablelist> - -</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --add-fixed sha256 ./hello-2.10.tar.gz -/nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz</screen> - -</refsection> - -</refsection> - - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-verify'><title>Operation <option>--verify</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--verify</option></arg> - <arg><option>--check-contents</option></arg> - <arg><option>--repair</option></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--verify</option> verifies the internal -consistency of the Nix database, and the consistency between the Nix -database and the Nix store. Any inconsistencies encountered are -automatically repaired. Inconsistencies are generally the result of -the Nix store or database being modified by non-Nix tools, or of bugs -in Nix itself.</para> - -<para>This operation has the following options: - -<variablelist> - - <varlistentry><term><option>--check-contents</option></term> - - <listitem><para>Checks that the contents of every valid store path - has not been altered by computing a SHA-256 hash of the contents - and comparing it with the hash stored in the Nix database at build - time. Paths that have been modified are printed out. For large - stores, <option>--check-contents</option> is obviously quite - slow.</para></listitem> - - </varlistentry> - - <varlistentry><term><option>--repair</option></term> - - <listitem><para>If any valid path is missing from the store, or - (if <option>--check-contents</option> is given) the contents of a - valid path has been modified, then try to repair the path by - redownloading it. See <command>nix-store --repair-path</command> - for details.</para></listitem> - - </varlistentry> - -</variablelist> - -</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--verify-path</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--verify-path</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--verify-path</option> compares the -contents of the given store paths to their cryptographic hashes stored -in Nix’s database. For every changed path, it prints a warning -message. The exit status is 0 if no path has changed, and 1 -otherwise.</para> - -</refsection> - -<refsection><title>Example</title> - -<para>To verify the integrity of the <command>svn</command> command and all its dependencies: - -<screen> -$ nix-store --verify-path $(nix-store -qR $(which svn)) -</screen> - -</para> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--repair-path</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--repair-path</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--repair-path</option> attempts to -“repair” the specified paths by redownloading them using the available -substituters. If no substitutes are available, then repair is not -possible.</para> - -<warning><para>During repair, there is a very small time window during -which the old path (if it exists) is moved out of the way and replaced -with the new path. If repair is interrupted in between, then the -system may be left in a broken state (e.g., if the path contains a -critical system component like the GNU C Library).</para></warning> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 -path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified! - expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588', - got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4' - -$ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13 -fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'... -… -</screen> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-dump'><title>Operation <option>--dump</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--dump</option></arg> - <arg choice='plain'><replaceable>path</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--dump</option> produces a NAR (Nix -ARchive) file containing the contents of the file system tree rooted -at <replaceable>path</replaceable>. The archive is written to -standard output.</para> - -<para>A NAR archive is like a TAR or Zip archive, but it contains only -the information that Nix considers important. For instance, -timestamps are elided because all files in the Nix store have their -timestamp set to 0 anyway. Likewise, all permissions are left out -except for the execute bit, because all files in the Nix store have -444 or 555 permission.</para> - -<para>Also, a NAR archive is <emphasis>canonical</emphasis>, meaning -that “equal” paths always produce the same NAR archive. For instance, -directory entries are always sorted so that the actual on-disk order -doesn’t influence the result. This means that the cryptographic hash -of a NAR dump of a path is usable as a fingerprint of the contents of -the path. Indeed, the hashes of store paths stored in Nix’s database -(see <link linkend="refsec-nix-store-query"><literal>nix-store -q ---hash</literal></link>) are SHA-256 hashes of the NAR dump of each -store path.</para> - -<para>NAR archives support filenames of unlimited length and 64-bit -file sizes. They can contain regular files, directories, and symbolic -links, but not other types of files (such as device nodes).</para> - -<para>A Nix archive can be unpacked using <literal>nix-store ---restore</literal>.</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--restore</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--restore</option></arg> - <arg choice='plain'><replaceable>path</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--restore</option> unpacks a NAR archive -to <replaceable>path</replaceable>, which must not already exist. The -archive is read from standard input.</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-export'><title>Operation <option>--export</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--export</option></arg> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--export</option> writes a serialisation -of the specified store paths to standard output in a format that can -be imported into another Nix store with <command -linkend="refsec-nix-store-import">nix-store --import</command>. This -is like <command linkend="refsec-nix-store-dump">nix-store ---dump</command>, except that the NAR archive produced by that command -doesn’t contain the necessary meta-information to allow it to be -imported into another Nix store (namely, the set of references of the -path).</para> - -<para>This command does not produce a <emphasis>closure</emphasis> of -the specified paths, so if a store path references other store paths -that are missing in the target Nix store, the import will fail. To -copy a whole closure, do something like: - -<screen> -$ nix-store --export $(nix-store -qR <replaceable>paths</replaceable>) > out</screen> - -To import the whole closure again, run: - -<screen> -$ nix-store --import < out</screen> - -</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection xml:id='refsec-nix-store-import'><title>Operation <option>--import</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--import</option></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--import</option> reads a serialisation of -a set of store paths produced by <command -linkend="refsec-nix-store-export">nix-store --export</command> from -standard input and adds those store paths to the Nix store. Paths -that already exist in the Nix store are ignored. If a path refers to -another path that doesn’t exist in the Nix store, the import -fails.</para> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--optimise</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--optimise</option></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--optimise</option> reduces Nix store disk -space usage by finding identical files in the store and hard-linking -them to each other. It typically reduces the size of the store by -something like 25-35%. Only regular files and symlinks are -hard-linked in this manner. Files are considered identical when they -have the same NAR archive serialisation: that is, regular files must -have the same contents and permission (executable or non-executable), -and symlinks must have the same contents.</para> - -<para>After completion, or when the command is interrupted, a report -on the achieved savings is printed on standard error.</para> - -<para>Use <option>-vv</option> or <option>-vvv</option> to get some -progress indication.</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --optimise -hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1' -<replaceable>...</replaceable> -541838819 bytes (516.74 MiB) freed by hard-linking 54143 files; -there are 114486 files with equal contents out of 215894 files in total -</screen> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--read-log</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <group choice='req'> - <arg choice='plain'><option>--read-log</option></arg> - <arg choice='plain'><option>-l</option></arg> - </group> - <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--read-log</option> prints the build log -of the specified store paths on standard output. The build log is -whatever the builder of a derivation wrote to standard output and -standard error. If a store path is not a derivation, the deriver of -the store path is used.</para> - -<para>Build logs are kept in -<filename>/nix/var/log/nix/drvs</filename>. However, there is no -guarantee that a build log is available for any particular store path. -For instance, if the path was downloaded as a pre-built binary through -a substitute, then the log is unavailable.</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store -l $(which ktorrent) -building /nix/store/dhc73pvzpnzxhdgpimsd9sw39di66ph1-ktorrent-2.2.1 -unpacking sources -unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz -ktorrent-2.2.1/ -ktorrent-2.2.1/NEWS -<replaceable>...</replaceable> -</screen> - -</refsection> - - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--dump-db</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--dump-db</option></arg> - <arg rep='repeat'><replaceable>paths</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--dump-db</option> writes a dump of the -Nix database to standard output. It can be loaded into an empty Nix -store using <option>--load-db</option>. This is useful for making -backups and when migrating to different database schemas.</para> - -<para>By default, <option>--dump-db</option> will dump the entire Nix -database. When one or more store paths is passed, only the subset of -the Nix database for those store paths is dumped. As with -<option>--export</option>, the user is responsible for passing all the -store paths for a closure. See <option>--export</option> for an -example.</para> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--load-db</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--load-db</option></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--load-db</option> reads a dump of the Nix -database created by <option>--dump-db</option> from standard input and -loads it into the Nix database.</para> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection><title>Operation <option>--print-env</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'><option>--print-env</option></arg> - <arg choice='plain'><replaceable>drvpath</replaceable></arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>The operation <option>--print-env</option> prints out the -environment of a derivation in a format that can be evaluated by a -shell. The command line arguments of the builder are placed in the -variable <envar>_args</envar>.</para> - -</refsection> - -<refsection><title>Example</title> - -<screen> -$ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox) -<replaceable>…</replaceable> -export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2' -export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv' -export system; system='x86_64-linux' -export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh' -</screen> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection xml:id='rsec-nix-store-generate-binary-cache-key'><title>Operation <option>--generate-binary-cache-key</option></title> - -<refsection> - <title>Synopsis</title> - <cmdsynopsis> - <command>nix-store</command> - <arg choice='plain'> - <option>--generate-binary-cache-key</option> - <option>key-name</option> - <option>secret-key-file</option> - <option>public-key-file</option> - </arg> - </cmdsynopsis> -</refsection> - -<refsection><title>Description</title> - -<para>This command generates an <link -xlink:href="http://ed25519.cr.yp.to/">Ed25519 key pair</link> that can -be used to create a signed binary cache. It takes three mandatory -parameters: - -<orderedlist> - - <listitem><para>A key name, such as - <literal>cache.example.org-1</literal>, that is used to look up keys - on the client when it verifies signatures. It can be anything, but - it’s suggested to use the host name of your cache - (e.g. <literal>cache.example.org</literal>) with a suffix denoting - the number of the key (to be incremented every time you need to - revoke a key).</para></listitem> - - <listitem><para>The file name where the secret key is to be - stored.</para></listitem> - - <listitem><para>The file name where the public key is to be - stored.</para></listitem> - -</orderedlist> - -</para> - -</refsection> - -</refsection> - - -<!--######################################################################--> - -<refsection condition="manpage"><title>Environment variables</title> - -<variablelist> - <xi:include href="env-common.xml#xmlns(db=http://docbook.org/ns/docbook)xpointer(//db:variablelist[@xml:id='env-common']/*)" /> -</variablelist> - -</refsection> - - -</refentry> diff --git a/doc/manual/command-ref/opt-common-syn.xml b/doc/manual/command-ref/opt-common-syn.xml deleted file mode 100644 index 2660e3bb1..000000000 --- a/doc/manual/command-ref/opt-common-syn.xml +++ /dev/null @@ -1,68 +0,0 @@ -<nop xmlns="http://docbook.org/ns/docbook"> - -<arg><option>--help</option></arg> -<arg><option>--version</option></arg> -<arg rep='repeat'> - <group choice='req'> - <arg choice='plain'><option>--verbose</option></arg> - <arg choice='plain'><option>-v</option></arg> - </group> -</arg> -<arg> - <arg choice='plain'><option>--quiet</option></arg> -</arg> -<arg> - <option>--log-format</option> - <replaceable>format</replaceable> -</arg> -<arg> - <group choice='plain'> - <arg choice='plain'><option>--no-build-output</option></arg> - <arg choice='plain'><option>-Q</option></arg> - </group> -</arg> -<arg> - <group choice='req'> - <arg choice='plain'><option>--max-jobs</option></arg> - <arg choice='plain'><option>-j</option></arg> - </group> - <replaceable>number</replaceable> -</arg> -<arg> - <option>--cores</option> - <replaceable>number</replaceable> -</arg> -<arg> - <option>--max-silent-time</option> - <replaceable>number</replaceable> -</arg> -<arg> - <option>--timeout</option> - <replaceable>number</replaceable> -</arg> -<arg> - <group choice='plain'> - <arg choice='plain'><option>--keep-going</option></arg> - <arg choice='plain'><option>-k</option></arg> - </group> -</arg> -<arg> - <group choice='plain'> - <arg choice='plain'><option>--keep-failed</option></arg> - <arg choice='plain'><option>-K</option></arg> - </group> -</arg> -<arg><option>--fallback</option></arg> -<arg><option>--readonly-mode</option></arg> -<arg> - <option>-I</option> - <replaceable>path</replaceable> -</arg> -<arg> - <option>--option</option> - <replaceable>name</replaceable> - <replaceable>value</replaceable> -</arg> -<sbr /> - -</nop> diff --git a/doc/manual/command-ref/opt-common.xml b/doc/manual/command-ref/opt-common.xml deleted file mode 100644 index a68eef1d0..000000000 --- a/doc/manual/command-ref/opt-common.xml +++ /dev/null @@ -1,405 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" xml:id="sec-common-options"> - -<title>Common Options</title> - - -<para>Most Nix commands accept the following command-line options:</para> - -<variablelist xml:id="opt-common"> - -<varlistentry><term><option>--help</option></term> - - <listitem><para>Prints out a summary of the command syntax and - exits.</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--version</option></term> - - <listitem><para>Prints out the Nix version number on standard output - and exits.</para></listitem> -</varlistentry> - - -<varlistentry><term><option>--verbose</option> / <option>-v</option></term> - - <listitem> - - <para>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.</para> - - <para>This option may be specified repeatedly. Currently, the - following verbosity levels exist:</para> - - <variablelist> - - <varlistentry><term>0</term> - <listitem><para>“Errors only”: only print messages - explaining why the Nix invocation failed.</para></listitem> - </varlistentry> - - <varlistentry><term>1</term> - <listitem><para>“Informational”: print - <emphasis>useful</emphasis> messages about what Nix is doing. - This is the default.</para></listitem> - </varlistentry> - - <varlistentry><term>2</term> - <listitem><para>“Talkative”: print more informational - messages.</para></listitem> - </varlistentry> - - <varlistentry><term>3</term> - <listitem><para>“Chatty”: print even more - informational messages.</para></listitem> - </varlistentry> - - <varlistentry><term>4</term> - <listitem><para>“Debug”: print debug - information.</para></listitem> - </varlistentry> - - <varlistentry><term>5</term> - <listitem><para>“Vomit”: print vast amounts of debug - information.</para></listitem> - </varlistentry> - - </variablelist> - - </listitem> - -</varlistentry> - - -<varlistentry><term><option>--quiet</option></term> - - <listitem> - - <para>Decreases the level of verbosity of diagnostic messages - printed on standard error. This is the inverse option to - <option>-v</option> / <option>--verbose</option>. - </para> - - <para>This option may be specified repeatedly. See the previous - verbosity levels list.</para> - - </listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-log-format"><term><option>--log-format</option> <replaceable>format</replaceable></term> - - <listitem> - - <para>This option can be used to change the output of the log format, with - <replaceable>format</replaceable> being one of:</para> - - <variablelist> - - <varlistentry><term>raw</term> - <listitem><para>This is the raw format, as outputted by nix-build.</para></listitem> - </varlistentry> - - <varlistentry><term>internal-json</term> - <listitem><para>Outputs the logs in a structured manner. NOTE: the json schema is not guarantees to be stable between releases.</para></listitem> - </varlistentry> - - <varlistentry><term>bar</term> - <listitem><para>Only display a progress bar during the builds.</para></listitem> - </varlistentry> - - <varlistentry><term>bar-with-logs</term> - <listitem><para>Display the raw logs, with the progress bar at the bottom.</para></listitem> - </varlistentry> - - </variablelist> - - </listitem> - -</varlistentry> - -<varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term> - - <listitem><para>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 - <filename><replaceable>prefix</replaceable>/nix/var/log/nix</filename>.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option> / <option>-j</option> -<replaceable>number</replaceable></term> - - <listitem> - - <para>Sets the maximum number of build jobs that Nix will - perform in parallel to the specified number. Specify - <literal>auto</literal> to use the number of CPUs in the system. - The default is specified by the <link - linkend='conf-max-jobs'><literal>max-jobs</literal></link> - configuration setting, which itself defaults to - <literal>1</literal>. A higher value is useful on SMP systems or to - exploit I/O latency.</para> - - <para> Setting it to <literal>0</literal> disallows building on the local - machine, which is useful when you want builds to happen only on remote - builders.</para> - - </listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-cores"><term><option>--cores</option></term> - - <listitem><para>Sets the value of the <envar>NIX_BUILD_CORES</envar> - 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 <varname>enableParallelBuilding</varname> is set to - <literal>true</literal>, the builder passes the - <option>-j<replaceable>N</replaceable></option> flag to GNU Make. - It defaults to the value of the <link - linkend='conf-cores'><literal>cores</literal></link> - configuration setting, if set, or <literal>1</literal> otherwise. - The value <literal>0</literal> means that the builder should use all - available CPU cores in the system.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-max-silent-time"><term><option>--max-silent-time</option></term> - - <listitem><para>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 <link - linkend='conf-max-silent-time'><literal>max-silent-time</literal></link> - configuration setting. <literal>0</literal> means no - time-out.</para></listitem> - -</varlistentry> - -<varlistentry xml:id="opt-timeout"><term><option>--timeout</option></term> - - <listitem><para>Sets the maximum number of seconds that a builder - can run. The default is specified by the <link - linkend='conf-timeout'><literal>timeout</literal></link> - configuration setting. <literal>0</literal> means no - timeout.</para></listitem> - -</varlistentry> - -<varlistentry><term><option>--keep-going</option> / <option>-k</option></term> - - <listitem><para>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).</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--keep-failed</option> / <option>-K</option></term> - - <listitem><para>Specifies that in case of a build failure, the - temporary directory (usually in <filename>/tmp</filename>) in which - the build takes place should not be deleted. The path of the build - directory is printed as an informational message. - </para> - </listitem> -</varlistentry> - - -<varlistentry><term><option>--fallback</option></term> - - <listitem> - - <para>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.</para> - - <para>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).</para> - - </listitem> - -</varlistentry> - -<varlistentry><term><option>--no-build-hook</option></term> - - <listitem> - - <para>Disables the build hook mechanism. This allows to ignore remote - builders if they are setup on the machine.</para> - - <para>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.</para> - - </listitem> - -</varlistentry> - - - -<varlistentry><term><option>--readonly-mode</option></term> - - <listitem><para>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.</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--arg</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> - - <listitem><para>This option is accepted by - <command>nix-env</command>, <command>nix-instantiate</command>, - <command>nix-shell</command> and <command>nix-build</command>. - 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 <link linkend='ss-functions'>default value</link> - (e.g., <literal>{ <replaceable>argName</replaceable> ? - <replaceable>defaultValue</replaceable> }: - <replaceable>...</replaceable></literal>). With - <option>--arg</option>, 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 <replaceable>name</replaceable>, it will call it with value - <replaceable>value</replaceable>.</para> - - <para>For instance, the top-level <literal>default.nix</literal> in - Nixpkgs is actually a function: - -<programlisting> -{ # The system (e.g., `i686-linux') for which to build the packages. - system ? builtins.currentSystem - <replaceable>...</replaceable> -}: <replaceable>...</replaceable></programlisting> - - So if you call this Nix expression (e.g., when you do - <literal>nix-env -i <replaceable>pkgname</replaceable></literal>), - the function will be called automatically using the value <link - linkend='builtin-currentSystem'><literal>builtins.currentSystem</literal></link> - for the <literal>system</literal> argument. You can override this - using <option>--arg</option>, e.g., <literal>nix-env -i - <replaceable>pkgname</replaceable> --arg system - \"i686-freebsd\"</literal>. (Note that since the argument is a Nix - string literal, you have to escape the quotes.)</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--argstr</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> - - <listitem><para>This option is like <option>--arg</option>, only the - value is not a Nix expression but a string. So instead of - <literal>--arg system \"i686-linux\"</literal> (the outer quotes are - to keep the shell happy) you can say <literal>--argstr system - i686-linux</literal>.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-attr"><term><option>--attr</option> / <option>-A</option> -<replaceable>attrPath</replaceable></term> - - <listitem><para>Select an attribute from the top-level Nix - expression being evaluated. (<command>nix-env</command>, - <command>nix-instantiate</command>, <command>nix-build</command> and - <command>nix-shell</command> only.) The <emphasis>attribute - path</emphasis> <replaceable>attrPath</replaceable> is a sequence of - attribute names separated by dots. For instance, given a top-level - Nix expression <replaceable>e</replaceable>, the attribute path - <literal>xorg.xorgserver</literal> would cause the expression - <literal><replaceable>e</replaceable>.xorg.xorgserver</literal> to - be used. See <link - linkend='refsec-nix-env-install-examples'><command>nix-env - --install</command></link> for some concrete examples.</para> - - <para>In addition to attribute names, you can also specify array - indices. For instance, the attribute path - <literal>foo.3.bar</literal> selects the <literal>bar</literal> - attribute of the fourth element of the array in the - <literal>foo</literal> attribute of the top-level - expression.</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--expr</option> / <option>-E</option></term> - - <listitem><para>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. - (<command>nix-instantiate</command>, <command>nix-build</command> - and <command>nix-shell</command> only.)</para> - - <para>For <command>nix-shell</command>, 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 - <emphasis>built</emphasis> packages ready for use, give your - expression to the <command>nix-shell -p</command> convenience flag - instead.</para></listitem> - -</varlistentry> - - -<varlistentry xml:id="opt-I"><term><option>-I</option> <replaceable>path</replaceable></term> - - <listitem><para>Add a path to the Nix expression search path. This - option may be given multiple times. See the <envar - linkend="env-NIX_PATH">NIX_PATH</envar> environment variable for - information on the semantics of the Nix search path. Paths added - through <option>-I</option> take precedence over - <envar>NIX_PATH</envar>.</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--option</option> <replaceable>name</replaceable> <replaceable>value</replaceable></term> - - <listitem><para>Set the Nix configuration option - <replaceable>name</replaceable> to <replaceable>value</replaceable>. - This overrides settings in the Nix configuration file (see - <citerefentry><refentrytitle>nix.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para></listitem> - -</varlistentry> - - -<varlistentry><term><option>--repair</option></term> - - <listitem><para>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 - <command>nix-store --repair-path</command>.</para></listitem> - -</varlistentry> - - -</variablelist> - - -</chapter> diff --git a/doc/manual/command-ref/opt-inst-syn.xml b/doc/manual/command-ref/opt-inst-syn.xml deleted file mode 100644 index e8c3f1ec6..000000000 --- a/doc/manual/command-ref/opt-inst-syn.xml +++ /dev/null @@ -1,22 +0,0 @@ -<nop xmlns="http://docbook.org/ns/docbook"> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--prebuilt-only</option></arg> - <arg choice='plain'><option>-b</option></arg> - </group> - </arg> - - <arg> - <group choice='req'> - <arg choice='plain'><option>--attr</option></arg> - <arg choice='plain'><option>-A</option></arg> - </group> - </arg> - - <arg><option>--from-expression</option></arg> - <arg><option>-E</option></arg> - - <arg><option>--from-profile</option> <replaceable>path</replaceable></arg> - -</nop> diff --git a/doc/manual/command-ref/utilities.xml b/doc/manual/command-ref/utilities.xml deleted file mode 100644 index 893f5b5b5..000000000 --- a/doc/manual/command-ref/utilities.xml +++ /dev/null @@ -1,20 +0,0 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id='ch-utilities'> - -<title>Utilities</title> - -<para>This section lists utilities that you can use when you -work with Nix.</para> - -<xi:include href="nix-channel.xml" /> -<xi:include href="nix-collect-garbage.xml" /> -<xi:include href="nix-copy-closure.xml" /> -<xi:include href="nix-daemon.xml" /> -<xi:include href="nix-hash.xml" /> -<xi:include href="nix-instantiate.xml" /> -<xi:include href="nix-prefetch-url.xml" /> - -</chapter> |