Auto merge of #9524 - ehuss:rustflags-compatibility, r=alexcrichton

Add a note about rustflags compatibility.

Over time, Cargo occasionally starts issuing new flags that may conflict with flags the user is passing directly to the compiler. Some recent examples are `-C embed-bitcode` (which broke anyone passing `-Clto` manually), and `-C prefer-dynamic` (which is kind of a mess). Future conflicts might be things like `--remap-path-prefix` or `--extern-html-root-url` (for rustdoc). This adds a note to mention these potential conflicts.

Although we try to maintain backwards compatibility as much as possible throughout all of Cargo, this particular area I think is dangerous enough that it is prudent to have some kind of warning somewhere. It is very rare that conflicts arise in practice, but they can happen.

I also added a note about passing in flags that Cargo itself issues, which can cause problems. Closes #9358.

Author: bors

src/doc/src/reference/config.md

@@ -349,6 +349,16 @@ Without `--target`, the flags will be passed to all compiler invocations
 you have args that you do not want to pass to build scripts or proc macros and
 are building for the host, pass `--target` with the host triple.
 
+It is not recommended to pass in flags that Cargo itself usually manages. For
+example, the flags driven by [profiles] are best handled by setting the
+appropriate profile setting.
+
+> **Caution**: Due to the low-level nature of passing flags directly to the
+> compiler, this may cause a conflict with future versions of Cargo which may
+> issue the same or similar flags on its own which may interfere with the
+> flags you specify. This is an area where Cargo may not always be backwards
+> compatible.
+
 ##### `build.rustdocflags`
 * Type: string or array of strings
 * Default: none