Convert commands

doc/manual/src/command-ref/nix-build.md

@@ -0,0 +1,130 @@
+nix-build
+
+1
+
+Nix
+
+nix-build
+
+build a Nix expression
+
+nix-build
+
+\--arg
+
+name
+
+value
+
+\--argstr
+
+name
+
+value
+
+\--attr
+
+\-A
+
+attrPath
+
+\--no-out-link
+
+\--dry-run
+
+\--out-link
+
+\-o
+
+outlink
+
+paths
+
+# Description
+
+The `nix-build` command builds the derivations described by the Nix
+expressions in paths. If the build succeeds, it places a symlink to the
+result in the current directory. The symlink is called `result`. If
+there are multiple Nix expressions, or the Nix expressions evaluate to
+multiple derivations, multiple sequentially numbered symlinks are
+created (`result`, `result-2`, and so on).
+
+If no paths are specified, then `nix-build` will use `default.nix` in
+the current directory, if it exists.
+
+If an element of paths starts with `http://` or `https://`, 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 `default.nix`.
+
+`nix-build` is essentially a wrapper around
+[`nix-instantiate`](#sec-nix-instantiate) (to translate a high-level Nix
+expression to a low-level store derivation) and [`nix-store
+--realise`](#rsec-nix-store-realise) (to build the store derivation).
+
+> **Warning**
+> 
+> The result of the build is automatically registered as a root of the
+> Nix garbage collector. This root disappears automatically when the
+> `result` symlink is deleted or renamed. So don’t rename the symlink.
+
+# Options
+
+All options not listed here are passed to `nix-store
+--realise`, except for `--arg` and `--attr` / `-A` which are passed to
+`nix-instantiate`. See also [???](#sec-common-options).
+
+  - `--no-out-link`  
+    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 `nix-store
+                    --gc`.
+
+  - `--dry-run`  
+    Show what store paths would be built or downloaded.
+
+  - `--out-link` / `-o` outlink  
+    Change the name of the symlink to the output path created from
+    `result` to outlink.
+
+The following common options are supported:
+
+# Examples
+
+    $ 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  ...  result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7
+    
+    $ ls ./result/bin/
+    firefox  firefox-config
+
+If a derivation has multiple outputs, `nix-build` will build the default
+(first) output. You can also build all outputs:
+
+    $ nix-build '<nixpkgs>' -A openssl.all
+
+This will create a symlink for each output named `result-outputname`.
+The suffix is omitted if the output name is `out`. So if `openssl` has
+outputs `out`, `bin` and `man`, `nix-build` will create symlinks
+`result`, `result-bin` and `result-man`. It’s also possible to build a
+specific output:
+
+    $ nix-build '<nixpkgs>' -A openssl.man
+
+This will create a symlink `result-man`.
+
+Build a Nix expression given on the command line:
+
+    $ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
+    $ cat ./result
+    bar
+
+Build the GNU Hello package from the latest revision of the master
+branch of Nixpkgs:
+
+    $ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
+
+# Environment variables