about summary refs log tree commit diff
path: root/doc/manual/command-ref
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual/command-ref')
-rw-r--r--doc/manual/command-ref/conf-file.xml15
-rw-r--r--doc/manual/command-ref/nix-channel.xml58
-rw-r--r--doc/manual/command-ref/nix-install-package.xml35
-rw-r--r--doc/manual/command-ref/nix-instantiate.xml2
-rw-r--r--doc/manual/command-ref/nix-pull.xml7
-rw-r--r--doc/manual/command-ref/nix-push.xml10
-rw-r--r--doc/manual/command-ref/nix-shell.xml24
-rw-r--r--doc/manual/command-ref/nix-store.xml4
-rw-r--r--doc/manual/command-ref/utilities.xml4
9 files changed, 114 insertions, 45 deletions
diff --git a/doc/manual/command-ref/conf-file.xml b/doc/manual/command-ref/conf-file.xml
index c3ef184e7368..053f4d43cb0c 100644
--- a/doc/manual/command-ref/conf-file.xml
+++ b/doc/manual/command-ref/conf-file.xml
@@ -66,7 +66,7 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</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 safe a bit of disk space (or a lot if
+    Turn it off to save a bit of disk space (or a lot if
     <literal>gc-keep-outputs</literal> is also turned on).</para></listitem>
 
   </varlistentry>
@@ -297,7 +297,7 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
   </varlistentry>
 
 
-  <varlistentry><term><literal>build-cache-failures</literal></term>
+  <varlistentry><term><literal>build-cache-failure</literal></term>
 
     <listitem><para>If set to <literal>true</literal>, Nix will
     “cache” build failures, meaning that it will remember (in its
@@ -348,7 +348,7 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
 
     <listitem><para>A list of URLs of binary caches, separated by
     whitespace.  The default is
-    <literal>http://cache.nixos.org</literal>.</para></listitem>
+    <literal>https://cache.nixos.org</literal>.</para></listitem>
 
   </varlistentry>
 
@@ -402,6 +402,15 @@ flag, e.g. <literal>--option gc-keep-outputs false</literal>.</para>
   </varlistentry>
 
 
+  <varlistentry><term><literal>verify-https-binary-caches</literal></term>
+
+    <listitem><para>Whether HTTPS binary caches are required to have a
+    certificate that can be verified. Defaults to
+    <literal>true</literal>.</para></listitem>
+
+  </varlistentry>
+
+
   <varlistentry><term><literal>force-manifest</literal></term>
 
     <listitem><para>If this option is set to <literal>false</literal>
diff --git a/doc/manual/command-ref/nix-channel.xml b/doc/manual/command-ref/nix-channel.xml
index c4cc04ce24d8..531b41fc0902 100644
--- a/doc/manual/command-ref/nix-channel.xml
+++ b/doc/manual/command-ref/nix-channel.xml
@@ -21,7 +21,7 @@
     <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>url</replaceable></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>
@@ -33,8 +33,8 @@
 
 <para>A Nix channel is 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
-and a <command>nix-push</command> manifest.  <phrase
+just a URL that points to a place containing both a set of Nix
+expressions and a pointer to a binary cache.  <phrase
 condition="manual">See also <xref linkend="sec-channels"
 />.</phrase></para>
 
@@ -99,13 +99,6 @@ an update.</para>
 <para>The list of subscribed channels is stored in
 <filename>~/.nix-channels</filename>.</para>
 
-<para>A channel consists of two elements: a bzipped Tar archive
-containing the Nix expressions, and a manifest created by
-<command>nix-push</command>.  These must be stored under
-<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal> and
-<literal><replaceable>url</replaceable>/MANIFEST</literal>,
-respectively.</para>
-
 </refsection>
 
 <refsection><title>Examples</title>
@@ -163,4 +156,49 @@ $ nix-instantiate --eval -E '(import &lt;nixpkgs> {}).lib.nixpkgsVersion'
 
 </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
+    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>
+
+  <varlistentry><term><filename>binary-cache-url</filename></term>
+
+    <listitem><para>A file containing the URL to a binary cache (such
+    as <uri>https://cache.nixos.org</uri>. Nix will automatically
+    check this cache for pre-built binaries, if the user has
+    sufficient rights to add binary caches. For instance, in a
+    multi-user Nix setup, the binary caches provided by the channels
+    of the root user are used automatically, but caches corresponding
+    to the channels of non-root users are ignored. Binary caches can
+    be created and maintained using
+    <command>nix-push</command>.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><filename>MANIFEST.bz2</filename></term>
+
+    <listitem><para>(Deprecated in favour of binary caches.) A
+    manifest as created by <command>nix-push</command>. Only used if
+    <filename>binary-cache-url</filename> is not present or if the
+    <filename>nix.conf</filename> option
+    <option>force-manifest</option> is set.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</refsection>
+
 </refentry>
diff --git a/doc/manual/command-ref/nix-install-package.xml b/doc/manual/command-ref/nix-install-package.xml
index 7d5cd996e44a..f7802a95d55e 100644
--- a/doc/manual/command-ref/nix-install-package.xml
+++ b/doc/manual/command-ref/nix-install-package.xml
@@ -3,7 +3,7 @@
       xmlns:xi="http://www.w3.org/2001/XInclude"
       version="5.0"
       xml:id="sec-nix-install-package">
-  
+
 <refmeta>
   <refentrytitle>nix-install-package</refentrytitle>
   <manvolnum>1</manvolnum>
@@ -47,8 +47,7 @@
 <para>The command <command>nix-install-package</command> interactively
 installs a Nix Package file (<filename>*.nixpkg</filename>), which is
 a small file that contains a store path to be installed along with the
-URL of a <link linkend="sec-nix-push"><command>nix-push</command>
-manifest</link>.  The Nix Package file is either
+URL of a binary cache.  The Nix Package file is either
 <replaceable>file</replaceable>, or automatically downloaded from
 <replaceable>url</replaceable> if the <option>--url</option> switch is
 used.</para>
@@ -76,7 +75,7 @@ to restart itself with <command>xterm</command>,
 <refsection><title>Options</title>
 
 <variablelist>
-  
+
   <varlistentry><term><option>--non-interactive</option></term>
 
     <listitem><para>Do not open a new terminal window and do not ask
@@ -139,14 +138,14 @@ The elements are as follows:
 <variablelist>
 
   <varlistentry><term><literal>NIXPKG1</literal></term>
-  
+
     <listitem><para>The version of the Nix Package
     file.</para></listitem>
 
   </varlistentry>
 
   <varlistentry><term><replaceable>manifestURL</replaceable></term>
-  
+
     <listitem><para>The manifest to be pulled by
     <command>nix-pull</command>.  The manifest must contain
     <replaceable>outPath</replaceable>.</para></listitem>
@@ -154,21 +153,21 @@ The elements are as follows:
   </varlistentry>
 
   <varlistentry><term><replaceable>name</replaceable></term>
-  
+
     <listitem><para>The symbolic name and version of the
     package.</para></listitem>
 
   </varlistentry>
 
   <varlistentry><term><replaceable>system</replaceable></term>
-  
+
     <listitem><para>The platform identifier of the platform for which
     this binary package is intended.</para></listitem>
 
   </varlistentry>
 
   <varlistentry><term><replaceable>drvPath</replaceable></term>
-  
+
     <listitem><para>The path in the Nix store of the derivation from
     which <replaceable>outPath</replaceable> was built.  Not currently
     used.</para></listitem>
@@ -176,17 +175,21 @@ The elements are as follows:
   </varlistentry>
 
   <varlistentry><term><replaceable>outPath</replaceable></term>
-  
-    <listitem><para>The path in the Nix store of the package.  After
-    <command>nix-install-package</command> has obtained the manifest
-    from <replaceable>manifestURL</replaceable>, it performs a
-    <literal>nix-env -i</literal> <replaceable>outPath</replaceable>
-    to install the binary package.</para></listitem>
+
+    <listitem><para>The path in the Nix store of the
+    package.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><replaceable>binaryCacheURL</replaceable></term>
+
+    <listitem><para>The URL of a binary cache containing the closure
+    of <replaceable>outPath</replaceable>.</para></listitem>
 
   </varlistentry>
 
 </variablelist>
-  
+
 </para>
 
 <para>An example follows:
diff --git a/doc/manual/command-ref/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml
index d4966579ae59..1e556c7ed7c4 100644
--- a/doc/manual/command-ref/nix-instantiate.xml
+++ b/doc/manual/command-ref/nix-instantiate.xml
@@ -45,7 +45,7 @@
     <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
     <sbr/>
     <command>nix-instantiate</command>
-    <arg choice='plain'><option>--file-file</option></arg>
+    <arg choice='plain'><option>--find-file</option></arg>
     <arg choice='plain' rep='repeat'><replaceable>files</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
diff --git a/doc/manual/command-ref/nix-pull.xml b/doc/manual/command-ref/nix-pull.xml
index 598c651b5091..eb471677b63f 100644
--- a/doc/manual/command-ref/nix-pull.xml
+++ b/doc/manual/command-ref/nix-pull.xml
@@ -13,7 +13,7 @@
 
 <refnamediv>
   <refname>nix-pull</refname>
-  <refpurpose>pull substitutes from a network cache</refpurpose>
+  <refpurpose>register availability of pre-built binaries (deprecated)</refpurpose>
 </refnamediv>
 
 <refsynopsisdiv>
@@ -26,6 +26,9 @@
 
 <refsection><title>Description</title>
 
+<note><para>This command and the use of manifests is deprecated. It is
+better to use binary caches.</para></note>
+
 <para>The command <command>nix-pull</command> obtains a list of
 pre-built store paths from the URL <replaceable>url</replaceable>, and
 for each of these store paths, registers a substitute derivation that
@@ -43,7 +46,7 @@ with the files created by <replaceable>nix-push</replaceable>.</para>
 <refsection><title>Examples</title>
 
 <screen>
-$ nix-pull http://nix.cs.uu.nl/dist/nix/nixpkgs-0.5pre753/MANIFEST</screen>
+$ nix-pull https://nixos.org/releases/nixpkgs/nixpkgs-15.05pre54468.69858d7/MANIFEST</screen>
 
 </refsection>
 
diff --git a/doc/manual/command-ref/nix-push.xml b/doc/manual/command-ref/nix-push.xml
index c19f44a615a8..a3a3c9623e3c 100644
--- a/doc/manual/command-ref/nix-push.xml
+++ b/doc/manual/command-ref/nix-push.xml
@@ -260,7 +260,7 @@ The properties that are currently supported are:
     <listitem><para>Each binary cache has a priority (defaulting to
     50).  Binary caches are checked for binaries in order of ascending
     priority; thus a higher number denotes a lower priority.  The
-    binary cache <uri>http://cache.nixos.org</uri> has priority
+    binary cache <uri>https://cache.nixos.org</uri> has priority
     40.</para></listitem>
 
   </varlistentry>
@@ -278,14 +278,14 @@ URL <replaceable>url</replaceable> has a binary for
 <replaceable>p</replaceable>, Nix fetches
 <replaceable>url/h</replaceable>, where <replaceable>h</replaceable>
 is the hash part of <replaceable>p</replaceable>.  Thus, if we have a
-cache <uri>http://cache.nixos.org</uri> and we want to obtain
-the store path
+cache <uri>https://cache.nixos.org</uri> and we want to obtain the
+store path
 <screen>
 /nix/store/a8922c0h87iilxzzvwn2hmv8x210aqb9-glibc-2.7
 </screen>
 then Nix will attempt to fetch
 <screen>
-http://cache.nixos.org/a8922c0h87iilxzzvwn2hmv8x210aqb9.narinfo
+https://cache.nixos.org/a8922c0h87iilxzzvwn2hmv8x210aqb9.narinfo
 </screen>
 (Commands such as <command>nix-env -qas</command> will issue an HTTP
 HEAD request, since it only needs to know if the
@@ -389,7 +389,7 @@ The fields are as follows:
 references exist (e.g.,
 <filename>/nix/store/2ma2k0ys8knh4an48n28vigcmc2z8773-linux-headers-2.6.23.16</filename>),
 Nix will fetch <screen>
-http://cache.nixos.org/nar/0zzjpdz46mdn74v09m053yczlz4am038g8r74iy8w43gx8801h70.nar.bz2
+https://cache.nixos.org/nar/0zzjpdz46mdn74v09m053yczlz4am038g8r74iy8w43gx8801h70.nar.bz2
 </screen> and decompress and unpack it to
 <filename>/nix/store/a8922c0h87iilxzzvwn2hmv8x210aqb9-glibc-2.7</filename>.</para>
 
diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml
index 1f03117636c9..c1b172b70380 100644
--- a/doc/manual/command-ref/nix-shell.xml
+++ b/doc/manual/command-ref/nix-shell.xml
@@ -29,6 +29,7 @@
       <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>
     <group choice='req'>
@@ -92,11 +93,24 @@ also <xref linkend="sec-common-options" />.</phrase></para>
   <varlistentry><term><option>--command</option> <replaceable>cmd</replaceable></term>
 
     <listitem><para>In the environment of the derivation, run the
-    shell command <replaceable>cmd</replaceable> instead of starting
-    an interactive shell.  However, if you end the shell command with
-    <literal>return</literal>, you still get an interactive shell.
-    This can be useful for doing any additional
-    initialisation.</para></listitem>
+    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>
 
diff --git a/doc/manual/command-ref/nix-store.xml b/doc/manual/command-ref/nix-store.xml
index e1e6c36e0c1d..a2faeaeba422 100644
--- a/doc/manual/command-ref/nix-store.xml
+++ b/doc/manual/command-ref/nix-store.xml
@@ -1277,7 +1277,7 @@ export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-buil
 <refsection><title>Description</title>
 
 <para>If build failure caching is enabled through the
-<literal>build-cache-failures</literal> configuration option, the
+<literal>build-cache-failure</literal> configuration option, the
 operation <option>--query-failed-paths</option> will print out all
 store paths that have failed to build.</para>
 
@@ -1314,7 +1314,7 @@ $ nix-store --query-failed-paths
 <refsection><title>Description</title>
 
 <para>If build failure caching is enabled through the
-<literal>build-cache-failures</literal> configuration option, the
+<literal>build-cache-failure</literal> configuration option, the
 operation <option>--clear-failed-paths</option> clears the “failed”
 state of the given store paths, allowing them to be built again.  This
 is useful if the failure was actually transient (e.g. because the disk
diff --git a/doc/manual/command-ref/utilities.xml b/doc/manual/command-ref/utilities.xml
index d5650fd38f43..be2fe6e2d235 100644
--- a/doc/manual/command-ref/utilities.xml
+++ b/doc/manual/command-ref/utilities.xml
@@ -13,7 +13,9 @@ work with Nix.</para>
 <xi:include href="nix-collect-garbage.xml" />
 <xi:include href="nix-copy-closure.xml" />
 <xi:include href="nix-daemon.xml" />
+<!--
 <xi:include href="nix-generate-patches.xml" />
+-->
 <xi:include href="nix-hash.xml" />
 <xi:include href="nix-install-package.xml" />
 <xi:include href="nix-instantiate.xml" />
@@ -21,4 +23,4 @@ work with Nix.</para>
 <xi:include href="nix-pull.xml" />
 <xi:include href="nix-push.xml" />
 
-</chapter>
\ No newline at end of file
+</chapter>
generated by cgit-pink 1.4.1 (git 2.44.2) at 2025-01-28T02·28+0000