Auto merge of #3865 - matklad:doc-all-the-things, r=alexcrichton

Beef up docs about integrating Cargo with other stuff

Add info about `--message-format=json`, `--dep-info` and custom cargo subcommands (mostly copy-pasted from the wiki :) ).

cc @carols10cents

r? @alexcrichton

Author: bors

Makefile.in

@@ -160,7 +160,7 @@ clean:
 
 DOCS := index faq config guide manifest build-script pkgid-spec crates-io \
 	environment-variables specifying-dependencies source-replacement \
-	policies machine-readable-output
+	policies external-tools
 DOC_DIR := target/doc
 DOC_OPTS := --markdown-no-toc \
 		--markdown-css stylesheets/normalize.css \

src/doc/external-tools.md

@@ -0,0 +1,103 @@
+% External tools
+
+One of the goals of Cargo is simple integration with third-party tools, like
+IDEs and other build systems. To make integration easier, Cargo has several
+facilities:
+
+* `cargo metadata` command, which outputs project structure and dependencies
+  information in JSON,
+
+* `--message-format` flag, which outputs information about a particular build,
+
+* support for custom subcommands.
+
+
+# Information about project structure
+
+
+You can use `cargo metadata` command to get information about project structure
+and dependencies. The output of the command looks like this:
+
+```text
+{
+  // Integer version number of the format.
+  "version": integer,
+
+  // List of packages for this workspace, including dependencies.
+  "packages": [
+    {
+      // Opaque package identifier.
+      "id": PackageId,
+
+      "name": string,
+
+      "version": string,
+
+      "source": SourceId,
+
+      // A list of declared dependencies, see `resolve` field for actual dependencies.
+      "dependencies": [ Dependency ],
+
+      "targets: [ Target ],
+
+      // Path to Cargo.toml
+      "manifest_path": string,
+    }
+  ],
+
+  "workspace_members": [ PackageId ],
+
+  // Dependencies graph.
+  "resolve": {
+     "nodes": [
+       {
+         "id": PackageId,
+         "dependencies": [ PackageId ]
+       }
+     ]
+  }
+}
+```
+
+The format is stable and versioned. When calling `cargo metadata`, you should
+pass `--format-version` flag explicitly to avoid forward incompatibility
+hazard.
+
+If you are using Rust, there is [cargo_metadata] crate.
+
+[cargo_metadata]: https://crates.io/crates/cargo_metadata
+
+
+# Information about build
+
+When passing `--message=format=json`, Cargo will output the following
+information during the build:
+
+* compiler errors and warnings,
+
+* produced artifacts,
+
+* results of the build scripts (for example, native dependencies).
+
+The output goes to stdout in the JSON object per line format. The `reason` field
+distinguishes different kinds of messages.
+
+Information about dependencies in the Makefile-compatible format is stored in
+the `.d` files alongside the artifacts.
+
+
+# Custom subcommands.
+
+Cargo is designed to be extensible with new subcommands without having to modify
+Cargo itself. This is achieved by translating a cargo invocation of the form
+cargo `(?<command>[^ ]+)` into an invocation of an external tool
+`cargo-${command}` that then needs to be present in one of the user's `$PATH`
+directories.
+
+Custom subcommand may use `CARGO` environment variable to call back to
+Cargo. Alternatively, it can link to `cargo` crate as a library, but this
+approach has drawbacks:
+
+* Cargo as a library is unstable, API changes without deprecation,
+
+* versions of Cargo library and Cargo binary may be different.

src/doc/header.html

@@ -27,7 +27,9 @@ <h1>CARGO</h1>
                 Docs
                 <span class="arrow"></span>
             </button>
-            <!-- Sync this list with https://github.com/rust-lang/crates.io/blob/master/app/templates/application.hbs -->
+            <!-- Sync this list with
+                 https://github.com/rust-lang/crates.io/blob/master/app/templates/application.hbs
+                 and with Makefile.in in this repository -->
             <ul id="current-user-links" class="dropdown" data-bindattr-503="503">
                 <li><a href='index.html'>Getting Started</a></li>
                 <li><a href='guide.html'>Guide</a></li>
@@ -40,7 +42,7 @@ <h1>CARGO</h1>
                 <li><a href='pkgid-spec.html'>Package ID specs</a></li>
                 <li><a href='environment-variables.html'>Environment Variables</a></li>
                 <li><a href='source-replacement.html'>Source Replacement</a></li>
-                <li><a href='machine-readable-output.html'>Machine readable output</a></li>
+                <li><a href='external-tools.html'>External Tools</a></li>
                 <li><a href='policies.html'>Policies</a></li>
             </ul>
         </div>