Don't warn about metadata keys in the manifest

External tools may want to store metadata in `Cargo.toml` that they read but
Cargo itself doesn't read. For example `cargo-apk` uses this for pieces of
configuration. Cargo unfortunately, however, warns about these keys as "unused
keys in the manifest"

This commit instead whitelists the `package.metadata` key to not warn about any
data inside.

src/cargo/util/toml.rs

@@ -134,6 +134,9 @@ pub fn to_manifest(contents: &[u8],
     return Ok((manifest, paths));
 
     fn add_unused_keys(m: &mut Manifest, toml: &toml::Value, key: String) {
+        if key == "package.metadata" {
+            return
+        }
         match *toml {
             toml::Value::Table(ref table) => {
                 for (k, v) in table.iter() {

src/doc/manifest.md

@@ -126,6 +126,25 @@ provide useful information to users of the registry and also influence the
 search ranking of a crate. It is highly discouraged to omit everything in a
 published crate.
 
+## The `metadata` Table (optional)
+
+Cargo by default will warn about unused keys in `Cargo.toml` to assist in
+detecting typos and such. The `package.metadata` table, however, is completely
+ignored by Cargo and will not be warned about. This section can be used for
+tools which would like to store project configuration in `Cargo.toml`. For
+example:
+
+```toml
+[package]
+name = "..."
+# ...
+
+# Metadata used when generating an Android APK, for example.
+[package.metadata.android]
+package-name = "my-awesome-android-app"
+assets = "path/to/static"
+```
+
 # Dependency Sections
 
 See the [specifying dependencies page](specifying-dependencies.html) for

tests/build.rs

@@ -2240,3 +2240,26 @@ fn explicit_color_config_is_propagated_to_rustc() {
         -L dependency=[..]target[..]debug[..]deps`
 "));
 }
+
+#[test]
+fn no_warn_about_package_metadata() {
+    let p = project("foo")
+        .file("Cargo.toml", r#"
+            [package]
+            name = "foo"
+            version = "0.0.1"
+            authors = []
+
+            [package.metadata]
+            foo = "bar"
+            a = true
+            b = 3
+
+            [package.metadata.another]
+            bar = 3
+        "#)
+        .file("src/lib.rs", "");
+    assert_that(p.cargo_process("build"),
+                execs().with_status(0)
+                       .with_stderr("[..] foo v0.0.1 ([..])\n"));
+}