From b54e8ecc2e0eec9ab9d0b1c1d9cb55f7602800c4 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sun, 29 Sep 2019 18:20:03 -0700 Subject: [PATCH] Update extern linking documentation. --- src/doc/rustc/src/codegen-options/index.md | 6 ++++- src/doc/rustc/src/command-line-arguments.md | 28 ++++++++++++++++----- 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md index 70c7acccd3638..0dc81378e05b2 100644 --- a/src/doc/rustc/src/codegen-options/index.md +++ b/src/doc/rustc/src/codegen-options/index.md @@ -197,7 +197,11 @@ in software. ## prefer-dynamic By default, `rustc` prefers to statically link dependencies. This option will -make it use dynamic linking instead. +indicate that dynamic linking should be used if possible if both a static and +dynamic versions of a library are available. There is an internal algorithm +for determining whether or not it is possible to statically or dynamically +link with a dependency. For example, `cdylib` crate types may only use static +linkage. ## no-integrated-as diff --git a/src/doc/rustc/src/command-line-arguments.md b/src/doc/rustc/src/command-line-arguments.md index 5887a0869e68c..561856db54b0d 100644 --- a/src/doc/rustc/src/command-line-arguments.md +++ b/src/doc/rustc/src/command-line-arguments.md @@ -21,8 +21,7 @@ to `#[cfg(verbose)]` and `#[cfg(feature = "serde")]` respectively. ## `-L`: add a directory to the library search path -When looking for external crates or libraries, a directory passed to this flag -will be searched. +The `-L` flag adds a path to search for external crates and libraries. The kind of search path can optionally be specified with the form `-L KIND=PATH` where `KIND` may be one of: @@ -262,15 +261,32 @@ This flag, when combined with other flags, makes them produce extra output. ## `--extern`: specify where an external library is located -This flag allows you to pass the name and location of an external crate that -will be linked into the crate you are building. This flag may be specified -multiple times. This flag takes an argument with either of the following -formats: +This flag allows you to pass the name and location for an external crate of a +direct dependency. Indirect dependencies (dependencies of dependencies) are +located using the [`-L` flag](#option-l-search-path). The given crate name is +added to the [extern prelude], which is the same as specifying `extern crate` +within the root module. The given crate name does not need to match the name +the library was built with. + +This flag may be specified multiple times. This flag takes an argument with +either of the following formats: * `CRATENAME=PATH` — Indicates the given crate is found at the given path. * `CRATENAME` — Indicates the given crate may be found in the search path, such as within the sysroot or via the `-L` flag. +The same crate name may be specified multiple times for different crate types. +For loading metadata, `rlib` takes precedence over `rmeta`, which takes +precedence over `dylib`. If both an `rlib` and `dylib` are found, an internal +algorithm is used to decide which to use for linking. The [`-C prefer-dynamic` +flag][prefer-dynamic] may be used to influence which is used. + +If the same crate name is specified with and without a path, the one with the +path is used and the pathless flag has no effect. + +[extern prelude]: ../reference/items/extern-crates.html#extern-prelude +[prefer-dynamic]: codegen-options/index.md#prefer-dynamic + ## `--sysroot`: Override the system root