src/doc/unstable-book/src/compiler-flags/extern-location.md

   1 # `extern-location`
   2
   3 MCP for this feature: [#303]
   4
   5 [#303]: https://github.com/rust-lang/compiler-team/issues/303
   6
   7 ------------------------
   8
   9 The `unused-extern-crates` lint reports when a crate was specified on the rustc
  10 command-line with `--extern name=path` but no symbols were referenced in it.
  11 This is useful to know, but it's hard to map that back to a specific place a user
  12 or tool could fix (ie, to remove the unused dependency).
  13
  14 The `--extern-location` flag allows the build system to associate a location with
  15 the `--extern` option, which is then emitted as part of the diagnostics. This location
  16 is abstract and just round-tripped through rustc; the compiler never attempts to
  17 interpret it in any way.
  18
  19 There are two supported forms of location: a bare string, or a blob of json:
  20 - `--extern-location foo=raw:Makefile:123` would associate the raw string `Makefile:123`
  21 - `--extern-location 'bar=json:{"target":"//my_project:library","dep":"//common:serde"}` would
  22   associate the json structure with `--extern bar=<path>`, indicating which dependency of
  23   which rule introduced the unused extern crate.
  24
  25 This primarily intended to be used with tooling - for example a linter which can automatically
  26 remove unused dependencies - rather than being directly presented to users.
  27
  28 `raw` locations are presented as part of the normal rendered diagnostics and included in
  29 the json form. `json` locations are only included in the json form of diagnostics,
  30 as a `tool_metadata` field. For `raw` locations `tool_metadata` is simply a json string,
  31 whereas `json` allows the rustc invoker to fully control its form and content.