Merge pull request #4336 from NixOS/manpages

Documentation for nix subcommands

81 files changed, 3246 insertions, 486 deletions

diff --git a/doc/manual/generate-manpage.nix b/doc/manual/generate-manpage.nix
index fbd7f3e7d..c2c748464 100644
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@@ -20,11 +20,6 @@ let
            (attrNames def.commands))
          + "\n"
        else "")
-    + (if def.examples or [] != []
-       then
-         "# Examples\n\n"
-         + concatStrings (map ({ description, command }: "${description}\n\n```console\n${command}\n```\n\n") def.examples)
-       else "")
     + (if def ? doc
        then def.doc + "\n\n"
        else "")
@@ -43,7 +38,7 @@ let
         if flag.category or "" != "config"
         then
           "  - `--${longName}`"
-          + (if flag ? shortName then " / `${flag.shortName}`" else "")
+          + (if flag ? shortName then " / `-${flag.shortName}`" else "")
           + (if flag ? labels then " " + (concatStringsSep " " (map (s: "*${s}*") flag.labels)) else "")
           + "  \n"
           + "    " + flag.description + "\n\n"
diff --git a/src/libutil/args.cc b/src/libutil/args.cc
index 61f9503ec..fb5cb80fb 100644
--- a/src/libutil/args.cc
+++ b/src/libutil/args.cc
@@ -254,6 +254,8 @@ nlohmann::json Args::toJSON()
     res["description"] = description();
     res["flags"] = std::move(flags);
     res["args"] = std::move(args);
+    auto s = doc();
+    if (s != "") res.emplace("doc", stripIndentation(s));
     return res;
 }
 
@@ -351,38 +353,6 @@ void printTable(std::ostream & out, const Table2 & table)
     }
 }
 
-void Command::printHelp(const string & programName, std::ostream & out)
-{
-    Args::printHelp(programName, out);
-
-    auto exs = examples();
-    if (!exs.empty()) {
-        out << "\n" ANSI_BOLD "Examples:" ANSI_NORMAL "\n";
-        for (auto & ex : exs)
-            out << "\n"
-                << "  " << ex.description << "\n" // FIXME: wrap
-                << "  $ " << ex.command << "\n";
-    }
-}
-
-nlohmann::json Command::toJSON()
-{
-    auto exs = nlohmann::json::array();
-
-    for (auto & example : examples()) {
-        auto ex = nlohmann::json::object();
-        ex["description"] = example.description;
-        ex["command"] = chomp(stripIndentation(example.command));
-        exs.push_back(std::move(ex));
-    }
-
-    auto res = Args::toJSON();
-    res["examples"] = std::move(exs);
-    auto s = doc();
-    if (s != "") res.emplace("doc", stripIndentation(s));
-    return res;
-}
-
 MultiCommand::MultiCommand(const Commands & commands)
     : commands(commands)
 {
diff --git a/src/libutil/args.hh b/src/libutil/args.hh
index 8069fd70f..6ed541a32 100644
--- a/src/libutil/args.hh
+++ b/src/libutil/args.hh
@@ -25,6 +25,9 @@ public:
     /* Return a short one-line description of the command. */
     virtual std::string description() { return ""; }
 
+    /* Return documentation about this command, in Markdown format. */
+    virtual std::string doc() { return ""; }
+
 protected:
 
     static const size_t ArityAny = std::numeric_limits<size_t>::max();
@@ -225,28 +228,11 @@ struct Command : virtual Args
     virtual void prepare() { };
     virtual void run() = 0;
 
-    /* Return documentation about this command, in Markdown format. */
-    virtual std::string doc() { return ""; }
-
-    struct Example
-    {
-        std::string description;
-        std::string command;
-    };
-
-    typedef std::list<Example> Examples;
-
-    virtual Examples examples() { return Examples(); }
-
     typedef int Category;
 
     static constexpr Category catDefault = 0;
 
     virtual Category category() { return catDefault; }
-
-    void printHelp(const string & programName, std::ostream & out) override;
-
-    nlohmann::json toJSON() override;
 };
 
 typedef std::map<std::string, std::function<ref<Command>()>> Commands;
diff --git a/src/nix/build.cc b/src/nix/build.cc
index 67be4024b..c2974d983 100644
--- a/src/nix/build.cc
+++ b/src/nix/build.cc
@@ -43,22 +43,11 @@ struct CmdBuild : InstallablesCommand, MixDryRun, MixJSON, MixProfile
         return "build a derivation or fetch a store path";
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-            Example{
-                "To build and run GNU Hello from NixOS 17.03:",
-                "nix build -f channel:nixos-17.03 hello; ./result/bin/hello"
-            },
-            Example{
-                "To build the build.x86_64-linux attribute from release.nix:",
-                "nix build -f release.nix build.x86_64-linux"
-            },
-            Example{
-                "To make a profile point at GNU Hello:",
-                "nix build --profile /tmp/profile nixpkgs#hello"
-            },
-        };
+        return
+          #include "build.md"
+          ;
     }
 
     void run(ref<Store> store) override
diff --git a/src/nix/build.md b/src/nix/build.md
new file mode 100644
index 000000000..c2f3e387a
--- /dev/null
+++ b/src/nix/build.md
@@ -0,0 +1,92 @@
+R""(
+
+# Examples
+
+* Build the default package from the flake in the current directory:
+
+  ```console
+  # nix build
+  ```
+
+* Build and run GNU Hello from the `nixpkgs` flake:
+
+  ```console
+  # nix build nixpkgs#hello
+  # ./result/bin/hello
+  Hello, world!
+  ```
+
+* Build GNU Hello and Cowsay, leaving two result symlinks:
+
+  ```console
+  # nix build nixpkgs#hello nixpkgs#cowsay
+  # ls -l result*
+  lrwxrwxrwx 1 … result -> /nix/store/v5sv61sszx301i0x6xysaqzla09nksnd-hello-2.10
+  lrwxrwxrwx 1 … result-1 -> /nix/store/rkfrm0z6x6jmi7d3gsmma4j53h15mg33-cowsay-3.03+dfsg2
+  ```
+
+* Build a specific output:
+
+  ```console
+  # nix build nixpkgs#glibc.dev
+  # ls -ld ./result-dev
+  lrwxrwxrwx 1 … ./result-dev -> /nix/store/dkm3gwl0xrx0wrw6zi5x3px3lpgjhlw4-glibc-2.32-dev
+  ```
+
+* Build attribute `build.x86_64-linux` from (non-flake) Nix expression
+  `release.nix`:
+
+  ```console
+  # nix build -f release.nix build.x86_64-linux
+  ```
+
+* Build a NixOS system configuration from a flake, and make a profile
+  point to the result:
+
+  ```console
+  # nix build --profile /nix/var/nix/profiles/system \
+      ~/my-configurations#nixosConfigurations.machine.config.system.build.toplevel
+  ```
+
+  (This is essentially what `nixos-rebuild` does.)
+
+* Build an expression specified on the command line:
+
+  ```console
+  # nix build --impure --expr \
+      'with import <nixpkgs> {};
+       runCommand "foo" {
+         buildInputs = [ hello ];
+       }
+       "hello > $out"'
+  # cat ./result
+  Hello, world!
+  ```
+
+  Note that `--impure` is needed because we're using `<nixpkgs>`,
+  which relies on the `$NIX_PATH` environment variable.
+
+* Fetch a store path from the configured substituters, if it doesn't
+  already exist:
+
+  ```console
+  # nix build /nix/store/rkfrm0z6x6jmi7d3gsmma4j53h15mg33-cowsay-3.03+dfsg2
+  ```
+
+# Description
+
+`nix build` builds the specified *installables*. Installables that
+resolve to derivations are built (or substituted if possible). Store
+path installables are substituted.
+
+Unless `--no-link` is specified, after a successful build, it creates
+symlinks to the store paths of the installables. These symlinks have
+the prefix `./result` by default; this can be overriden using the
+`--out-link` option. Each symlink has a suffix `-<N>-<outname>`, where
+*N* is the index of the installable (with the left-most installable
+having index 0), and *outname* is the symbolic derivation output name
+(e.g. `bin`, `dev` or `lib`). `-<N>` is omitted if *N* = 0, and
+`-<outname>` is omitted if *outname* = `out` (denoting the default
+output).
+
+)""
diff --git a/src/nix/bundle.cc b/src/nix/bundle.cc
index eddd82f40..5f558b01e 100644
--- a/src/nix/bundle.cc
+++ b/src/nix/bundle.cc
@@ -40,14 +40,11 @@ struct CmdBundle : InstallableCommand
         return "bundle an application so that it works outside of the Nix store";
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-            Example{
-                "To bundle Hello:",
-                "nix bundle hello"
-            },
-        };
+        return
+          #include "bundle.md"
+          ;
     }
 
     Category category() override { return catSecondary; }
diff --git a/src/nix/bundle.md b/src/nix/bundle.md
new file mode 100644
index 000000000..5e2298376
--- /dev/null
+++ b/src/nix/bundle.md
@@ -0,0 +1,36 @@
+R""(
+
+# Examples
+
+* Bundle Hello:
+
+  ```console
+  # nix bundle nixpkgs#hello
+  # ./hello
+  Hello, world!
+  ```
+
+* Bundle a specific version of Nix:
+
+  ```console
+  # nix bundle github:NixOS/nix/e3ddffb27e5fc37a209cfd843c6f7f6a9460a8ec
+  # ./nix --version
+  nix (Nix) 2.4pre20201215_e3ddffb
+  ```
+
+# Description
+
+`nix bundle` packs the closure of the [Nix app](./nix3-run.md)
+*installable* into a single self-extracting executable. See the
+[`nix-bundle` homepage](https://github.com/matthewbauer/nix-bundle)
+for more details.
+
+> **Note**
+>
+> This command only works on Linux.
+
+# Bundler definitions
+
+TODO
+
+)""
diff --git a/src/nix/cat.cc b/src/nix/cat.cc
index 2ecffc9a5..e28ee3c50 100644
--- a/src/nix/cat.cc
+++ b/src/nix/cat.cc
@@ -37,6 +37,13 @@ struct CmdCatStore : StoreCommand, MixCat
         return "print the contents of a file in the Nix store on stdout";
     }
 
+    std::string doc() override
+    {
+        return
+          #include "store-cat.md"
+          ;
+    }
+
     void run(ref<Store> store) override
     {
         cat(store->getFSAccessor());
@@ -62,6 +69,13 @@ struct CmdCatNar : StoreCommand, MixCat
         return "print the contents of a file inside a NAR file on stdout";
     }
 
+    std::string doc() override
+    {
+        return
+          #include "nar-cat.md"
+          ;
+    }
+
     void run(ref<Store> store) override
     {
         cat(makeNarAccessor(make_ref<std::string>(readFile(narPath))));
diff --git a/src/nix/copy.cc b/src/nix/copy.cc
index cb31aac8f..2394eb46d 100644
--- a/src/nix/copy.cc
+++ b/src/nix/copy.cc
@@ -54,32 +54,11 @@ struct CmdCopy : StorePathsCommand
         return "copy paths between Nix stores";
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-            Example{
-                "To copy Firefox from the local store to a binary cache in file:///tmp/cache:",
-                "nix copy --to file:///tmp/cache $(type -p firefox)"
-            },
-            Example{
-                "To copy the entire current NixOS system closure to another machine via SSH:",
-                "nix copy --to ssh://server /run/current-system"
-            },
-            Example{
-                "To copy a closure from another machine via SSH:",
-                "nix copy --from ssh://server /nix/store/a6cnl93nk1wxnq84brbbwr6hxw9gp2w9-blender-2.79-rc2"
-            },
-#ifdef ENABLE_S3
-            Example{
-                "To copy Hello to an S3 binary cache:",
-                "nix copy --to s3://my-bucket?region=eu-west-1 nixpkgs#hello"
-            },
-            Example{
-                "To copy Hello to an S3-compatible binary cache:",
-                "nix copy --to s3://my-bucket?region=eu-west-1&endpoint=example.com nixpkgs#hello"
-            },
-#endif
-        };
+        return
+          #include "copy.md"
+          ;
     }
 
     Category category() override { return catSecondary; }
diff --git a/src/nix/copy.md b/src/nix/copy.md
new file mode 100644
index 000000000..25e0ddadc
--- /dev/null
+++ b/src/nix/copy.md
@@ -0,0 +1,58 @@
+R""(
+
+# Examples
+
+* Copy Firefox from the local store to a binary cache in `/tmp/cache`:
+
+  ```console
+  # nix copy --to file:///tmp/cache $(type -p firefox)
+  ```
+
+  Note the `file://` - without this, the destination is a chroot
+  store, not a binary cache.
+
+* Copy the entire current NixOS system closure to another machine via
+  SSH:
+
+  ```console
+  # nix copy -s --to ssh://server /run/current-system
+  ```
+
+  The `-s` flag causes the remote machine to try to substitute missing
+  store paths, which may be faster if the link between the local and
+  remote machines is slower than the link between the remote machine
+  and its substituters (e.g. `https://cache.nixos.org`).
+
+* Copy a closure from another machine via SSH:
+
+  ```console
+  # nix copy --from ssh://server /nix/store/a6cnl93nk1wxnq84brbbwr6hxw9gp2w9-blender-2.79-rc2
+  ```
+
+* Copy Hello to a binary cache in an Amazon S3 bucket:
+
+  ```console
+  # nix copy --to s3://my-bucket?region=eu-west-1 nixpkgs#hello
+  ```
+
+  or to an S3-compatible storage system:
+
+  ```console
+  # nix copy --to s3://my-bucket?region=eu-west-1&endpoint=example.com nixpkgs#hello
+  ```
+
+  Note that this only works if Nix is built with AWS support.
+
+* Copy a closure from `/nix/store` to the chroot store `/tmp/nix/nix/store`:
+
+  ```console
+  # nix copy --to /tmp/nix nixpkgs#hello --no-check-sigs
+  ```
+
+# Description
+
+`nix copy` copies store path closures between two Nix stores. The
+source store is specified using `--from` and the destination using
+`--to`. If one of these is omitted, it defaults to the local store.
+
+)""
diff --git a/src/nix/develop.cc b/src/nix/develop.cc
index 457d94382..edd87f246 100644
--- a/src/nix/develop.cc
+++ b/src/nix/develop.cc
@@ -385,30 +385,11 @@ struct CmdDevelop : Common, MixEnvironment
         return "run a bash shell that provides the build environment of a derivation";
     }
 
-    Examples examples() override
+    std::string doc() override
     {
-        return {
-            Example{
-                "To get the build environment of GNU hello:",
-                "nix develop nixpkgs#hello"
-            },
-            Example{
-                "To get the build environment of the default package of flake in the current directory:",
-                "nix develop"
-            },
-            Example{
-                "To store the build environment in a profile:",
-                "nix develop --profile /tmp/my-shell nixpkgs#hello"
-            },
-            Example{
-                "To use a build environment previously recorded in a profile:",
-                "nix develop /tmp/my-shell"
-            },
-            Example{
-                "To replace all occurences of a store path with a writa