diff options
| author | Manish Goregaokar <manishsmail@gmail.com> | 2020-06-23 00:34:03 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2020-06-23 00:34:03 -0700 |
| commit | 05601515be9e101c5746b32caad873a43bb93e8b (patch) | |
| tree | 550afb2b5816d3469c3717cfdf09c430ec1bcd1e | |
| parent | 0f9a6edc095048f29829d7e501008140fdfe54fd (diff) | |
| parent | a63eb3c67865ef0ae881642da7178a98e51a5a36 (diff) | |
| download | rust-05601515be9e101c5746b32caad873a43bb93e8b.tar.gz rust-05601515be9e101c5746b32caad873a43bb93e8b.zip | |
Rollup merge of #73567 - adetaylor:extern-doc-fix, r=dtolnay
Clarify --extern documentation. Fixes #64731, #73531. See also https://github.com/rust-lang/rust/issues/64402#issuecomment-530852886
| -rw-r--r-- | src/doc/rustc/src/command-line-arguments.md | 12 |
1 files changed, 10 insertions, 2 deletions
diff --git a/src/doc/rustc/src/command-line-arguments.md b/src/doc/rustc/src/command-line-arguments.md index 7a7838d965b..30b18eb56a1 100644 --- a/src/doc/rustc/src/command-line-arguments.md +++ b/src/doc/rustc/src/command-line-arguments.md @@ -273,10 +273,18 @@ This flag, when combined with other flags, makes them produce extra output. 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 +added to the [extern prelude], similar to specifying `extern crate` within the +root module. The given crate name does not need to match the name the library was built with. +Specifying `--extern` has one behavior difference from `extern crate`: +`--extern` merely makes the crate a _candidate_ for being linked; it does not +actually link it unless it's actively used. In rare occasions you may wish +to ensure a crate is linked even if you don't actively use it from your +code: for example, if it changes the global allocator or if it contains +`#[no_mangle]` symbols for use by other programming languages. In such +cases you'll need to use `extern crate`. + This flag may be specified multiple times. This flag takes an argument with either of the following formats: |