Skip to content

Stabilize --extern flag without a path. #64882

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bors merged 8 commits into from
Nov 8, 2019
Merged

Stabilize --extern flag without a path. #64882

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
b47e3d8
Stabilize --extern flag without a path.
ehuss Sep 28, 2019
e0058ce
Add more --extern tests.
ehuss Sep 30, 2019
4bf411e
Update built-in help for --extern.
ehuss Sep 30, 2019
b54e8ec
Update extern linking documentation.
ehuss Sep 30, 2019
41e051d
Update src/test/ui-fulldeps/pathless-extern-unstable.rs
ehuss Oct 7, 2019
f9e4f0f
Add test for --extern alloc=librustc.rlib
ehuss Oct 8, 2019
845ec5d
Remove docs on --extern metadata precedence.
ehuss Oct 16, 2019
ee459c6
Update for unstable option refactoring.
ehuss Oct 16, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update extern linking documentation.
  • Loading branch information
@ehuss
ehuss committed Nov 7, 2019
commit b54e8ecc2e0eec9ab9d0b1c1d9cb55f7602800c4
6 changes: 5 additions & 1 deletion src/doc/rustc/src/codegen-options/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
28 changes: 22 additions & 6 deletions src/doc/rustc/src/command-line-arguments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,7 @@ to `#[cfg(verbose)]` and `#[cfg(feature = "serde")]` respectively.
<a id="option-l-search-path"></a>
Copy link
Member

@GuillaumeGomez GuillaumeGomez Nov 7, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line is making the html check fails because the id is not unique.

## `-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:
Expand Down Expand Up @@ -262,15 +261,32 @@ This flag, when combined with other flags, makes them produce extra output.
<a id="option-extern"></a>
## `--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.
Copy link
Contributor

@Centril Centril Sep 28, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have tests ensuring that sysroot crates, e.g. private rustc details emit an error when used on a stable compiler? (Also when an explicit path is used to them, not just a search.)

Copy link
Contributor

@petrochenkov petrochenkov Sep 29, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What happens if both --extern CRATENAME=PATH and --extern CRATENAME are specified for the same CRATENAME? It would be nice to document that.
AFAIR, multiple --extern CRATENAME=PATHs with the same CRATENAME are possible if they lead to different kinds of libraries, like rlib and dylib.

Copy link
Contributor Author

@ehuss ehuss Sep 30, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are about 30 tests doing various things with pathless --extern (search for // compile-flags:.*--extern).

I have added some more specific tests:

  • run-make-fulldeps/extern-flag-pathless: Shows what happens when you mix pathless with path --extern flags. Also demonstrates the preference of rlib over dylib.
  • ui-fulldeps/pathless-extern-unstable.rs: Shows --extern rustc is not allowed.
  • ui/pathless-extern-ok.rs: Basic test for a sysroot crate.

I don't have a good intuition of how sophisticated rustc tests should be. They are also a bit disorganized, so I didn't know where to stick them, or which style would be preferred. I think the dylib tests should be safe from a cross platform standpoint (I believe they only run on Linux?).

I updated the documentation with some more detail. I never really know how detailed rustc docs should be. I intentionally left the prefer-dynamic algorithm vague. It is described somewhat in src/librustc_metadata/dependency_format.rs. I figure since it is complex, and possibly subject to change, it may not be worthwhile. I can add more or remove some if desired.


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

<a id="option-sysroot"></a>
## `--sysroot`: Override the system root

Expand Down