From 504b7abc452936b3118a18efea05026083ed8cdd Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <edolstra@gmail.com>
Date: Thu, 23 Jul 2020 12:58:42 +0200
Subject: Convert commands

---
 doc/manual/src/command-ref/nix-instantiate.md | 184 ++++++++++++++++++++++++++
 1 file changed, 184 insertions(+)
 create mode 100644 doc/manual/src/command-ref/nix-instantiate.md

(limited to 'doc/manual/src/command-ref/nix-instantiate.md')

diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md
new file mode 100644
index 000000000..449f5f70f
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-instantiate.md
@@ -0,0 +1,184 @@
+nix-instantiate
+
+1
+
+Nix
+
+nix-instantiate
+
+instantiate store derivations from Nix expressions
+
+nix-instantiate
+
+\--parse
+
+\--eval
+
+\--strict
+
+\--json
+
+\--xml
+
+\--read-write-mode
+
+\--arg
+
+name
+
+value
+
+\--attr
+
+\-A
+
+attrPath
+
+\--add-root
+
+path
+
+\--indirect
+
+\--expr
+
+\-E
+
+files
+
+nix-instantiate
+
+\--find-file
+
+files
+
+# Description
+
+The command `nix-instantiate` generates [store
+derivations](#gloss-derivation) from (high-level) Nix expressions. It
+evaluates the Nix expressions in each of files (which defaults to
+./default.nix). 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.
+
+If files is the character `-`, then a Nix expression will be read from
+standard input.
+
+See also [???](#sec-common-options) for a list of common options.
+
+# Options
+
+  - `--add-root` path; `--indirect`  
+    See the [corresponding options](#opt-add-root) in `nix-store`.
+
+  - `--parse`  
+    Just parse the input files, and print their abstract syntax trees on
+    standard output in ATerm format.
+
+  - `--eval`  
+    Just parse and evaluate the input files, and print the resulting
+    values on standard output. No instantiation of store derivations
+    takes place.
+
+  - `--find-file`  
+    Look up the given files in Nix’s search path (as specified by the
+    NIX\_PATH\</literal\> environment variable). If found, print the
+    corresponding absolute paths on standard output. For instance, if
+    `NIX_PATH` is `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate
+    --find-file nixpkgs/default.nix` will print
+    `/home/alice/nixpkgs/default.nix`.
+
+  - `--strict`  
+    When used with `--eval`, recursively evaluate list elements and
+    attributes. Normally, such sub-expressions are left unevaluated
+    (since the Nix expression language is lazy).
+    
+    > **Warning**
+    > 
+    > This option can cause non-termination, because lazy data
+    > structures can be infinitely large.
+
+  - `--json`  
+    When used with `--eval`, print the resulting value as an JSON
+    representation of the abstract syntax tree rather than as an ATerm.
+
+  - `--xml`  
+    When used with `--eval`, 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 [`toXML`
+    built-in](#builtin-toXML).
+
+  - `--read-write-mode`  
+    When used with `--eval`, 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.
+
+<!-- end list -->
+
+# Examples
+
+Instantiating store derivations from a Nix expression, and building them
+using `nix-store`:
+
+    $ nix-instantiate test.nix (instantiate)
+    /nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
+    
+    $ nix-store -r $(nix-instantiate test.nix) (build)
+    ...
+    /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path)
+    
+    $ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
+    dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
+    ...
+
+You can also give a Nix expression on the command line:
+
+    $ nix-instantiate -E 'with import <nixpkgs> { }; hello'
+    /nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
+
+This is equivalent to:
+
+    $ nix-instantiate '<nixpkgs>' -A hello
+
+Parsing and evaluating Nix expressions:
+
+    $ nix-instantiate --parse -E '1 + 2'
+    1 + 2
+    
+    $ nix-instantiate --eval -E '1 + 2'
+    3
+    
+    $ nix-instantiate --eval --xml -E '1 + 2'
+    <?xml version='1.0' encoding='utf-8'?>
+    <expr>
+      <int value="3" />
+    </expr>
+
+The difference between non-strict and strict evaluation:
+
+    $ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
+    ...
+      <attr name="x">
+        <string value="foo" />
+      </attr>
+      <attr name="y">
+        <unevaluated />
+      </attr>
+    ...
+
+Note that `y` is left unevaluated (the XML representation doesn’t
+attempt to show non-normal forms).
+
+    $ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
+    ...
+      <attr name="x">
+        <string value="foo" />
+      </attr>
+      <attr name="y">
+        <string value="foo" />
+      </attr>
+    ...
+
+# Environment variables
-- 
cgit v1.2.3