about summary refs log tree commit diff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/manual/Makefile.am40
-rw-r--r--doc/manual/env-common.xml2
-rw-r--r--doc/manual/installation.xml8
-rw-r--r--doc/manual/manual.xml3
-rw-r--r--doc/manual/nix-build.xml23
-rw-r--r--doc/manual/nix-channel.xml48
-rw-r--r--doc/manual/nix-copy-closure.xml8
-rw-r--r--doc/manual/nix-env.xml26
-rw-r--r--doc/manual/nix-instantiate.xml36
-rw-r--r--doc/manual/nix-store.xml36
-rw-r--r--doc/manual/opt-common.xml2
11 files changed, 162 insertions, 70 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 55450c9a5990..33cb27e054bd 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -1,5 +1,5 @@
-XMLLINT = $(xmllint) $(xmlflags)
-XSLTPROC = $(xsltproc) $(xmlflags) \
+XMLLINT = $(xmllint) --nonet $(xmlflags)
+XSLTPROC = $(xsltproc) --nonet $(xmlflags) \
  --param section.autolabel 1 \
  --param section.label.includes.component.label 1 \
  --param html.stylesheet \'style.css\' \
@@ -29,29 +29,41 @@ MANUAL_SRCS = manual.xml introduction.xml installation.xml \
  package-management.xml writing-nix-expressions.xml builtins.xml \
  build-farm.xml \
  $(man1_MANS:.1=.xml) $(man8_MANS:.8=.xml) \
- troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml \
+ troubleshooting.xml bugs.xml opt-common.xml opt-common-syn.xml opt-inst-syn.xml \
  env-common.xml quick-start.xml nix-lang-ref.xml glossary.xml \
  conf-file.xml release-notes.xml \
  style.css images
 
+# Do XInclude processing.
+manual.xmli: $(MANUAL_SRCS) version.txt
+	$(XMLLINT) --xinclude $< -o $@.tmp
+	mv $@.tmp $@
+
 # Note: RelaxNG validation requires xmllint >= 2.7.4.
-manual.is-valid: $(MANUAL_SRCS) version.txt
-	$(XMLLINT) --noout --nonet --xinclude --noxincludenode --relaxng $(docbookrng)/docbook.rng $<
+manual.is-valid: manual.xmli
+	$(XSLTPROC) --novalid --stringparam profile.condition manual \
+	  $(docbookxsl)/profiling/profile.xsl $< 2> /dev/null | \
+	  $(XMLLINT) --noout --relaxng $(docbookrng)/docbook.rng -
 	touch $@
 
 version.txt:
 	echo -n $(VERSION) > version.txt
 
-man $(MANS): $(MANUAL_SRCS) manual.is-valid
-	$(XSLTPROC) --nonet --xinclude $(docbookxsl)/manpages/docbook.xsl manual.xml
+man $(MANS): manual.is-valid
+	$(XSLTPROC) --stringparam profile.condition manpage \
+	  $(docbookxsl)/profiling/profile.xsl manual.xmli 2> /dev/null | \
+	  $(XSLTPROC) $(docbookxsl)/manpages/docbook.xsl -
 
 manual.html: $(MANUAL_SRCS) manual.is-valid images
-	$(XSLTPROC) --nonet --xinclude --output manual.html \
-	  $(docbookxsl)/html/docbook.xsl manual.xml
+	$(XSLTPROC) --xinclude --stringparam profile.condition manual \
+	  $(docbookxsl)/profiling/profile.xsl manual.xml | \
+	  $(XSLTPROC) --output manual.html $(docbookxsl)/html/docbook.xsl -
 
 manual.pdf: $(MANUAL_SRCS) manual.is-valid images
 	if test "$(dblatex)" != ""; then \
-		$(dblatex) $(dblatex_opts) manual.xml; \
+		$(XSLTPROC) --xinclude --stringparam profile.condition manual \
+		  $(docbookxsl)/profiling/profile.xsl manual.xml | \
+		  $(dblatex) -o manual.pdf $(dblatex_opts) -; \
 	else \
 		echo "Please install dblatex and rerun configure."; \
 		exit 1; \
@@ -64,12 +76,12 @@ NEWS_OPTS = \
  --stringparam header.rule 0
 
 NEWS.html: release-notes.xml
-	$(XSLTPROC) --nonet --xinclude --output $@ $(NEWS_OPTS) \
+	$(XSLTPROC) --xinclude --output $@ $(NEWS_OPTS) \
 	  $(docbookxsl)/html/docbook.xsl release-notes.xml
 
 NEWS.txt: release-notes.xml
-	$(XSLTPROC) --nonet --xinclude quote-literals.xsl release-notes.xml | \
-	  $(XSLTPROC) --nonet --output $@.tmp.html $(NEWS_OPTS) \
+	$(XSLTPROC) --xinclude quote-literals.xsl release-notes.xml | \
+	  $(XSLTPROC) --output $@.tmp.html $(NEWS_OPTS) \
 	  $(docbookxsl)/html/docbook.xsl -
 	LANG=en_US $(w3m) -dump $@.tmp.html > $@
 	rm $@.tmp.html
@@ -96,7 +108,7 @@ images:
 	cp $(docbookxsl)/images/callouts/*.gif images/callouts
 	chmod -R +w images
 
-KEEP = manual.html manual.is-valid version.txt $(MANS) NEWS.html NEWS.txt
+KEEP = manual.html manual.xmli manual.is-valid version.txt $(MANS) NEWS.html NEWS.txt
 
 EXTRA_DIST = $(MANUAL_SRCS) $(FIGURES) $(KEEP)
 
diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml
index 99acc5949044..f52e2633de78 100644
--- a/doc/manual/env-common.xml
+++ b/doc/manual/env-common.xml
@@ -7,7 +7,7 @@
 
 <para>Most Nix commands interpret the following environment variables:</para>
 
-<variablelist>
+<variablelist xml:id="env-common">
 
   
 <varlistentry><term><envar>NIX_IGNORE_SYMLINK_STORE</envar></term>
diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml
index 15c156dab5e7..5e29abe9f5f8 100644
--- a/doc/manual/installation.xml
+++ b/doc/manual/installation.xml
@@ -47,17 +47,17 @@ for Red Hat, SuSE, and Fedora Core are also available.</para>
 
 <para>Alternatively, the most recent sources of Nix can be obtained
 from its <link
-xlink:href="https://svn.nixos.org/repos/nix/nix/trunk">Subversion
+xlink:href="https://github.com/NixOS/nix">git
 repository</link>.  For example, the following command will check out
 the latest revision into a directory called
 <filename>nix</filename>:</para>
 
 <screen>
-$ svn checkout https://svn.nixos.org/repos/nix/nix/trunk nix</screen>
+$ git clone https://github.com/NixOS/nix</screen>
 
 <para>Likewise, specific releases can be obtained from the <link
-xlink:href="https://svn.nixos.org/repos/nix/nix/tags">tags
-directory</link> of the repository.</para>
+xlink:href="https://github.com/NixOS/nix/tags">tags
+</link> of the repository.</para>
 
 </section>
 
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 95f80686008d..fa80a3651dcf 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -14,8 +14,7 @@
         <surname>Dolstra</surname>
       </personname>
       <affiliation>
-        <orgname>Delft University of Technology</orgname>
-        <orgdiv>Department of Software Technology</orgdiv>
+        <orgname>LogicBlox</orgname>
       </affiliation>
       <contrib>Author</contrib>
     </author>
diff --git a/doc/manual/nix-build.xml b/doc/manual/nix-build.xml
index 465635f67125..e3508d92ce0e 100644
--- a/doc/manual/nix-build.xml
+++ b/doc/manual/nix-build.xml
@@ -75,11 +75,11 @@ or renamed.  So don’t rename the symlink.</para></warning>
 
 <refsection><title>Options</title>
 
-<para>See also <xref linkend="sec-common-options" />.  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>.</para>
+<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>
 
@@ -122,6 +122,10 @@ except for <option>--arg</option> and <option>--attr</option> /
 
 </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>
 
 
@@ -141,4 +145,13 @@ firefox  firefox-config</screen>
 </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/nix-channel.xml b/doc/manual/nix-channel.xml
index 024add8601e8..22d8900d8f1c 100644
--- a/doc/manual/nix-channel.xml
+++ b/doc/manual/nix-channel.xml
@@ -19,7 +19,7 @@
   <cmdsynopsis>
     <command>nix-channel</command>
     <group choice='req'>
-      <arg choice='plain'><option>--add</option> <replaceable>url</replaceable></arg>
+      <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>--list</option></arg>
       <arg choice='plain'><option>--update</option></arg>
@@ -31,32 +31,39 @@
 
 <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 that contains a set of Nix
-expressions, as well as a <command>nix-push</command> manifest.  See
-also <xref linkend="sec-channels" />.</para>
+just a URL that points to a place containing a set of Nix expressions
+and a <command>nix-push</command> manifest.  <phrase
+condition="manual">See also <xref linkend="sec-channels"
+/>.</phrase></para>
 
 <para>This command has the following operations:
 
 <variablelist>
 
-  <varlistentry><term><option>--add</option> <replaceable>url</replaceable></term>
+  <varlistentry><term><option>--add</option> <replaceable>url</replaceable> [<replaceable>name</replaceable>]</term>
 
-    <listitem><para>Adds <replaceable>url</replaceable> to the list of
-    subscribed channels.</para></listitem>
+    <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>url</replaceable></term>
+  <varlistentry><term><option>--remove</option> <replaceable>name</replaceable></term>
 
-    <listitem><para>Removes <replaceable>url</replaceable> from the
-    list of subscribed channels.</para></listitem>
+    <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 URLs of all subscribed channels on
-    standard output.</para></listitem>
+    <listitem><para>Prints the names and URLs of all subscribed
+    channels on standard output.</para></listitem>
 
   </varlistentry>
 
@@ -64,7 +71,7 @@ also <xref linkend="sec-channels" />.</para>
 
     <listitem><para>Downloads the Nix expressions of all subscribed
     channels, makes them the default for <command>nix-env</command>
-    operations (by symlinking them in the directory
+    operations (by symlinking them from the directory
     <filename>~/.nix-defexpr</filename>), and performs a
     <command>nix-pull</command> on the manifests of all channels to
     make pre-built binaries available.</para></listitem>
@@ -75,8 +82,8 @@ also <xref linkend="sec-channels" />.</para>
 
 </para>
 
-<para>Note that <option>--add</option> and <option>--remove</option>
-do not automatically perform an update.</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>
@@ -90,4 +97,15 @@ respectively.</para>
 
 </refsection>
 
+<refsection><title>Examples</title>
+
+<para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para>
+
+<screen>
+$ nix-channel --add http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable
+$ nix-channel --update
+$ nix-env -iA nixpkgs.hello</screen>
+
+</refsection>
+
 </refentry>
diff --git a/doc/manual/nix-copy-closure.xml b/doc/manual/nix-copy-closure.xml
index 45cfc0f34245..4b5ce755c67d 100644
--- a/doc/manual/nix-copy-closure.xml
+++ b/doc/manual/nix-copy-closure.xml
@@ -26,6 +26,7 @@
     <arg><option>--gzip</option></arg>
     <arg><option>--bzip2</option></arg>
     <arg><option>--xz</option></arg>
+    <arg><option>--show-progress</option></arg>
     <arg><option>--include-outputs</option></arg>
     <arg choice='plain'>
       <replaceable>user@</replaceable><replaceable>machine</replaceable>
@@ -110,6 +111,13 @@ those paths.  If this bothers you, use
 
   </varlistentry>
 
+  <varlistentry><term><option>--show-progress</option></term>
+
+    <listitem><para>Show the progress of each path's transfer as it's made.
+    This requires the <command>pv</command> utility to be in <envar>PATH</envar>.</para></listitem>
+
+  </varlistentry>
+
   <varlistentry><term><option>--include-outputs</option></term>
   
   <listitem><para>Also copy the outputs of store derivations included
diff --git a/doc/manual/nix-env.xml b/doc/manual/nix-env.xml
index a03afaf5c007..02a51c6e9006 100644
--- a/doc/manual/nix-env.xml
+++ b/doc/manual/nix-env.xml
@@ -18,7 +18,7 @@
 <refsynopsisdiv>
   <cmdsynopsis>
     <command>nix-env</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/*)" />
+    <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>
@@ -71,8 +71,8 @@ be performed.  These are documented below.</para>
 
 <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.  See also <xref
-linkend="sec-common-options" />.</para>
+they may not always have an effect.  <phrase condition="manual">See
+also <xref linkend="sec-common-options" />.</phrase></para>
 
 <variablelist>
 
@@ -121,16 +121,18 @@ linkend="sec-common-options" />.</para>
   <varlistentry><term><option>--system-filter</option> <replaceable>system</replaceable></term>
 
     <listitem><para>By default, operations such as <option>--query
-    --available</option> only include derivations matching the current
-    platform.  This option allows you to use derivations for the
-    specified platform <replaceable>system</replaceable>.  The special
-    value <literal>*</literal> causes derivations for any platform to
-    be included.</para></listitem>
+    --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>
 
 
@@ -1250,5 +1252,13 @@ error: no generation older than the current (91) exists</screen>
 </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/nix-instantiate.xml b/doc/manual/nix-instantiate.xml
index ba89af425586..618b61f159dc 100644
--- a/doc/manual/nix-instantiate.xml
+++ b/doc/manual/nix-instantiate.xml
@@ -36,6 +36,7 @@
           <option>--eval-only</option>
           <arg><option>--strict</option></arg>
         </arg>
+        <arg choice='plain'><option>--find-file</option></arg>
       </group>
       <arg><option>--xml</option></arg>
     </arg>
@@ -49,8 +50,9 @@
 <para>The command <command>nix-instantiate</command> generates <link
 linkend="gloss-derivation">store derivations</link> from (high-level)
 Nix expressions.  It loads and evaluates the Nix expressions in each
-of <replaceable>files</replaceable>.  Each top-level expression should
-evaluate to a derivation, a list of derivations, or a set of
+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>
 
@@ -64,8 +66,8 @@ store derivation instantiation from Nix expressions automatically).
 It is most commonly used for implementing new deployment
 policies.</para>
 
-<para>See also <xref linkend="sec-common-options" /> for a list of
-common options.</para>
+<para condition="manual">See also <xref linkend="sec-common-options"
+/> for a list of common options.</para>
 
 </refsection>
 
@@ -100,6 +102,19 @@ common options.</para>
     
   </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>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>--xml</option></term>
 
     <listitem><para>When used with <option>--parse-only</option> and
@@ -127,6 +142,10 @@ common options.</para>
 
 </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>
 
 
@@ -198,4 +217,13 @@ $ echo 'rec { x = "foo"; y = x; }' | nix-instantiate --eval-only --xml --strict
 </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/nix-store.xml b/doc/manual/nix-store.xml
index a32559c033f4..6cc765bf27ca 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -48,8 +48,9 @@ be performed.  These are documented below.</para>
 
 <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.  See also <xref
-linkend="sec-common-options" /> for a list of common options.</para>
+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>
 
@@ -57,8 +58,9 @@ linkend="sec-common-options" /> for a list of common options.</para>
 
     <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 (see <xref
-    linkend="ssec-gc-roots" />).  The root is stored in
+    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
@@ -112,6 +114,10 @@ lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r1134
     
 </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>
 
   
@@ -212,7 +218,6 @@ linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
     <arg choice='plain'><option>--delete</option></arg>
   </group>
   <arg><option>--max-freed</option> <replaceable>bytes</replaceable></arg>
-  <arg><option>--max-links</option> <replaceable>nrlinks</replaceable></arg>
 </cmdsynopsis>
 
 </refsection>
@@ -280,16 +285,6 @@ options control what gets deleted and in what order:
     
   </varlistentry>
 
-  <varlistentry><term><option>--max-links</option> <replaceable>nrlinks</replaceable></term>
-  
-    <listitem><para>Keep deleting paths until the hard link count on
-    <filename>/nix/store</filename> is less than
-    <replaceable>nrlinks</replaceable>, then stop.  This is useful for
-    very large Nix stores on filesystems with a 32000 subdirectories
-    limit (like <literal>ext3</literal>).</para></listitem>
-    
-  </varlistentry>
-
 </variablelist>
 
 </para>
@@ -1053,7 +1048,7 @@ backups and when migrating to different database schemas.</para>
 
 <!--######################################################################-->
 
-<refsection><title>Operation <option>--dump-db</option></title>
+<refsection><title>Operation <option>--load-db</option></title>
 
 <refsection>
   <title>Synopsis</title>
@@ -1074,4 +1069,13 @@ loads it into the Nix database.</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/opt-common.xml b/doc/manual/opt-common.xml
index c36c6df41003..92b76c01f103 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -5,7 +5,7 @@
 
 <para>Most Nix commands accept the following command-line options:</para>
 
-<variablelist>
+<variablelist xml:id="opt-common">
 
 <varlistentry><term><option>--help</option></term>
generated by cgit-pink 1.4.1 (git 2.44.2) at 2025-02-05T09·52+0000