Reconvert

3 files changed, 335 insertions, 0 deletions

diff --git a/doc/manual/src/command-ref/command-ref.md b/doc/manual/src/command-ref/command-ref.md
index b15a50a3b..2c7dbf22e 100644
--- a/doc/manual/src/command-ref/command-ref.md
+++ b/doc/manual/src/command-ref/command-ref.md
@@ -1,2 +1,4 @@
+# Command Reference
+
 This section lists commands and options that you can use when you
 work with Nix.
diff --git a/doc/manual/src/command-ref/env-common.md b/doc/manual/src/command-ref/env-common.md
new file mode 100644
index 000000000..14e08e0f1
--- /dev/null
+++ b/doc/manual/src/command-ref/env-common.md
@@ -0,0 +1,112 @@
+# Common Environment Variables
+
+Most Nix commands interpret the following environment variables:
+
+  - `IN_NIX_SHELL`  
+    Indicator that tells if the current environment was set up by
+    `nix-shell`. Since Nix 2.0 the values are `"pure"` and `"impure"`
+
+  - `NIX_PATH`  
+    A colon-separated list of directories used to look up Nix
+    expressions enclosed in angle brackets (i.e., `<path>`). For
+    instance, the value
+    
+        /home/eelco/Dev:/etc/nixos
+    
+    will cause Nix to look for paths relative to `/home/eelco/Dev` and
+    `/etc/nixos`, in this order. It is also possible to match paths
+    against a prefix. For example, the value
+    
+        nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos
+    
+    will cause Nix to search for `<nixpkgs/path>` in
+    `/home/eelco/Dev/nixpkgs-branch/path` and `/etc/nixos/nixpkgs/path`.
+    
+    If a path in the Nix search path 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
+    consist of a single top-level directory. For example, setting
+    `NIX_PATH` to
+    
+        nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz
+    
+    tells Nix to download the latest revision in the Nixpkgs/NixOS 15.09
+    channel.
+    
+    A following shorthand can be used to refer to the official channels:
+    
+        nixpkgs=channel:nixos-15.09
+    
+    The search path can be extended using the `-I` option, which takes
+    precedence over `NIX_PATH`.
+
+  - `NIX_IGNORE_SYMLINK_STORE`  
+    Normally, the Nix store directory (typically `/nix/store`) 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 `/nix/store` resolving to different locations) could yield
+    different results. This is generally not a problem, except when
+    builds are deployed to machines where `/nix/store` resolves
+    differently. If you are sure that you’re not going to do that, you
+    can set `NIX_IGNORE_SYMLINK_STORE` to `1`.
+    
+    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 `bind` mount points, e.g.,
+    
+        $ mkdir /nix
+        $ mount -o bind /mnt/otherdisk/nix /nix
+    
+    Consult the mount 8 manual page for details.
+
+  - `NIX_STORE_DIR`  
+    Overrides the location of the Nix store (default `prefix/store`).
+
+  - `NIX_DATA_DIR`  
+    Overrides the location of the Nix static data directory (default
+    `prefix/share`).
+
+  - `NIX_LOG_DIR`  
+    Overrides the location of the Nix log directory (default
+    `prefix/var/log/nix`).
+
+  - `NIX_STATE_DIR`  
+    Overrides the location of the Nix state directory (default
+    `prefix/var/nix`).
+
+  - `NIX_CONF_DIR`  
+    Overrides the location of the system Nix configuration directory
+    (default `prefix/etc/nix`).
+
+  - `NIX_USER_CONF_FILES`  
+    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 `:` token.
+
+  - `TMPDIR`  
+    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 `/tmp`.
+
+  - `NIX_REMOTE`  
+    This variable should be set to `daemon` if you want to use the Nix
+    daemon to execute Nix operations. This is necessary in [multi-user
+    Nix installations](#ssec-multi-user). If the Nix daemon's Unix
+    socket is at some non-standard path, this variable should be set to
+    `unix://path/to/socket`. Otherwise, it should be left unset.
+
+  - `NIX_SHOW_STATS`  
+    If set to `1`, Nix will print some evaluation statistics, such as
+    the number of values allocated.
+
+  - `NIX_COUNT_CALLS`  
+    If set to `1`, Nix will print how often functions were called during
+    Nix expression evaluation. This is useful for profiling your Nix
+    expressions.
+
+  - `GC_INITIAL_HEAP_SIZE`  
+    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.
diff --git a/doc/manual/src/command-ref/opt-common.md b/doc/manual/src/command-ref/opt-common.md
new file mode 100644
index 000000000..ac9d996c3
--- /dev/null
+++ b/doc/manual/src/command-ref/opt-common.md
@@ -0,0 +1,221 @@
+# Common Options
+
+Most Nix commands accept the following command-line options:
+
+  - `--help`  
+    Prints out a summary of the command syntax and exits.
+
+  - `--version`  
+    Prints out the Nix version number on standard output and exits.
+
+  - `--verbose` / `-v`  
+    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.
+    
+    This option may be specified repeatedly. Currently, the following
+    verbosity levels exist:
+    
+      - 0  
+        “Errors only”: only print messages explaining why the Nix
+        invocation failed.
+    
+      - 1  
+        “Informational”: print *useful* messages about what Nix is
+        doing. This is the default.
+    
+      - 2  
+        “Talkative”: print more informational messages.
+    
+      - 3  
+        “Chatty”: print even more informational messages.
+    
+      - 4  
+        “Debug”: print debug information.
+    
+      - 5  
+        “Vomit”: print vast amounts of debug information.
+
+  - `--quiet`  
+    Decreases the level of verbosity of diagnostic messages printed on
+    standard error. This is the inverse option to `-v` / `--verbose`.
+    
+    This option may be specified repeatedly. See the previous verbosity
+    levels list.
+
+  - `--log-format` format  
+    This option can be used to change the output of the log format, with
+    format being one of:
+    
+      - raw  
+        This is the raw format, as outputted by nix-build.
+    
+      - internal-json  
+        Outputs the logs in a structured manner. NOTE: the json schema
+        is not guarantees to be stable between releases.
+    
+      - bar  
+        Only display a progress bar during the builds.
+    
+      - bar-with-logs  
+        Display the raw logs, with the progress bar at the bottom.
+
+  - `--no-build-output` / `-Q`  
+    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
+    `prefix/nix/var/log/nix`.
+
+  - `--max-jobs` / `-j` number  
+    Sets the maximum number of build jobs that Nix will perform in
+    parallel to the specified number. Specify `auto` to use the number
+    of CPUs in the system. The default is specified by the
+    [`max-jobs`](#conf-max-jobs) configuration setting, which itself
+    defaults to `1`. A higher value is useful on SMP systems or to
+    exploit I/O latency.
+    
+    Setting it to `0` disallows building on the local machine, which is
+    useful when you want builds to happen only on remote builders.
+
+  - `--cores`  
+    Sets the value of the `NIX_BUILD_CORES` 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
+    `enableParallelBuilding` is set to `true`, the builder passes the
+    `-jN` flag to GNU Make. It defaults to the value of the
+    [`cores`](#conf-cores) configuration setting, if set, or `1`
+    otherwise. The value `0` means that the builder should use all
+    available CPU cores in the system.
+
+  - `--max-silent-time`  
+    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 [`max-silent-time`](#conf-max-silent-time)
+    configuration setting. `0` means no time-out.
+
+  - `--timeout`  
+    Sets the maximum number of seconds that a builder can run. The
+    default is specified by the [`timeout`](#conf-timeout) configuration
+    setting. `0` means no timeout.
+
+  - `--keep-going` / `-k`  
+    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).
+
+  - `--keep-failed` / `-K`  
+    Specifies that in case of a build failure, the temporary directory
+    (usually in `/tmp`) in which the build takes place should not be
+    deleted. The path of the build directory is printed as an
+    informational message.
+
+  - `--fallback`  
+    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.
+    
+    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).
+
+  - `--no-build-hook`  
+    Disables the build hook mechanism. This allows to ignore remote
+    builders if they are setup on the machine.
+    
+    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.
+
+  - `--readonly-mode`  
+    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.
+
+  - `--arg` name value  
+    This option is accepted by `nix-env`, `nix-instantiate`, `nix-shell`
+    and `nix-build`. 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 [default value](#ss-functions) (e.g., `{ argName ?
+            defaultValue }:
+            ...`). With `--arg`, 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 name, it
+    will call it with value value.
+    
+    For instance, the top-level `default.nix` in Nixpkgs is actually a
+    function:
+    
+        { # The system (e.g., `i686-linux') for which to build the packages.
+          system ? builtins.currentSystem
+          ...
+        }: ...
+    
+    So if you call this Nix expression (e.g., when you do `nix-env -i
+    pkgname`), the function will be called automatically using the value
+    [`builtins.currentSystem`](#builtin-currentSystem) for the `system`
+    argument. You can override this using `--arg`, e.g., `nix-env -i
+            pkgname --arg system
+            \"i686-freebsd\"`. (Note that since the argument is a Nix string
+    literal, you have to escape the quotes.)
+
+  - `--argstr` name value  
+    This option is like `--arg`, only the value is not a Nix expression
+    but a string. So instead of `--arg system \"i686-linux\"` (the outer
+    quotes are to keep the shell happy) you can say `--argstr system
+            i686-linux`.
+
+  - `--attr` / `-A` attrPath  
+    Select an attribute from the top-level Nix expression being
+    evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and
+    `nix-shell` only.) The *attribute path* attrPath is a sequence of
+    attribute names separated by dots. For instance, given a top-level
+    Nix expression e, the attribute path `xorg.xorgserver` would cause
+    the expression `e.xorg.xorgserver` to be used. See [`nix-env
+            --install`](#refsec-nix-env-install-examples) for some concrete
+    examples.
+    
+    In addition to attribute names, you can also specify array indices.
+    For instance, the attribute path `foo.3.bar` selects the `bar`
+    attribute of the fourth element of the array in the `foo` attribute
+    of the top-level expression.
+
+  - `--expr` / `-E`  
+    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. (`nix-instantiate`, `nix-build` and `nix-shell` only.)
+    
+    For `nix-shell`, 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 *built* packages ready for
+    use, give your expression to the `nix-shell -p` convenience flag
+    instead.
+
+  - `-I` path  
+    Add a path to the Nix expression search path. This option may be
+    given multiple times. See the NIX\_PATH\</literal\> environment
+    variable for information on the semantics of the Nix search path.
+    Paths added through `-I` take precedence over `NIX_PATH`.
+
+  - `--option` name value  
+    Set the Nix configuration option name to value. This overrides
+    settings in the Nix configuration file (see nix.conf5).
+
+  - `--repair`  
+    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 `nix-store --repair-path`.