doc: Update the linkage documentation
After allowing mixing rlibs and dylibs in #13892, the documentation was not updated accordingly to reflect this new capability.
This commit is contained in:
parent
06ea9893d5
commit
e798b97ce9
1 changed files with 25 additions and 25 deletions
|
@ -4006,26 +4006,15 @@ compiler must at some point make a choice between these two formats. With this
|
||||||
in mind, the compiler follows these rules when determining what format of
|
in mind, the compiler follows these rules when determining what format of
|
||||||
dependencies will be used:
|
dependencies will be used:
|
||||||
|
|
||||||
1. If a dynamic library is being produced, then it is required for all upstream
|
1. If a static library is being produced, all upstream dependencies are
|
||||||
Rust dependencies to also be dynamic. This is a limitation of the current
|
|
||||||
implementation of the linkage model. The reason behind this limitation is to
|
|
||||||
prevent multiple copies of the same upstream library from showing up, and in
|
|
||||||
the future it is planned to support a mixture of dynamic and static linking.
|
|
||||||
|
|
||||||
When producing a dynamic library, the compiler will generate an error if an
|
|
||||||
upstream dependency could not be found, and also if an upstream dependency
|
|
||||||
could only be found in an `rlib` format. Remember that `staticlib` formats
|
|
||||||
are always ignored by `rustc` for crate-linking purposes.
|
|
||||||
|
|
||||||
2. If a static library is being produced, all upstream dependencies are
|
|
||||||
required to be available in `rlib` formats. This requirement stems from the
|
required to be available in `rlib` formats. This requirement stems from the
|
||||||
same reasons that a dynamic library must have all dynamic dependencies.
|
reason that a dynamic library cannot be converted into a static format.
|
||||||
|
|
||||||
Note that it is impossible to link in native dynamic dependencies to a static
|
Note that it is impossible to link in native dynamic dependencies to a static
|
||||||
library, and in this case warnings will be printed about all unlinked native
|
library, and in this case warnings will be printed about all unlinked native
|
||||||
dynamic dependencies.
|
dynamic dependencies.
|
||||||
|
|
||||||
3. If an `rlib` file is being produced, then there are no restrictions on what
|
2. If an `rlib` file is being produced, then there are no restrictions on what
|
||||||
format the upstream dependencies are available in. It is simply required that
|
format the upstream dependencies are available in. It is simply required that
|
||||||
all upstream dependencies be available for reading metadata from.
|
all upstream dependencies be available for reading metadata from.
|
||||||
|
|
||||||
|
@ -4033,18 +4022,29 @@ dependencies will be used:
|
||||||
dependencies. It wouldn't be very efficient for all `rlib` files to contain a
|
dependencies. It wouldn't be very efficient for all `rlib` files to contain a
|
||||||
copy of `libstd.rlib`!
|
copy of `libstd.rlib`!
|
||||||
|
|
||||||
4. If an executable is being produced, then things get a little interesting. As
|
3. If an executable is being produced and the `-C prefer-dynamic` flag is not
|
||||||
with the above limitations in dynamic and static libraries, it is required
|
specified, then dependencies are first attempted to be found in the `rlib`
|
||||||
for all upstream dependencies to be in the same format. The next question is
|
format. If some dependencies are not available in an rlib format, then
|
||||||
whether to prefer a dynamic or a static format. The compiler currently favors
|
dynamic linking is attempted (see below).
|
||||||
static linking over dynamic linking, but this can be inverted with the `-C
|
|
||||||
prefer-dynamic` flag to the compiler.
|
|
||||||
|
|
||||||
What this means is that first the compiler will attempt to find all upstream
|
4. If a dynamic library or an executable that is being dynamically linked is
|
||||||
dependencies as `rlib` files, and if successful, it will create a statically
|
being produced, then the compiler will attempt to reconcile the available
|
||||||
linked executable. If an upstream dependency is missing as an `rlib` file,
|
dependencies in either the rlib or dylib format to create a final product.
|
||||||
then the compiler will force all dependencies to be dynamic and will generate
|
|
||||||
errors if dynamic versions could not be found.
|
A major goal of the compiler is to ensure that a library never appears more
|
||||||
|
than once in any artifact. For example, if dynamic libraries B and C were
|
||||||
|
each statically linked to library A, then a crate could not link to B and C
|
||||||
|
together because there would be two copies of A. The compiler allows mixing
|
||||||
|
the rlib and dylib formats, but this restriction must be satisfied.
|
||||||
|
|
||||||
|
The compiler currently implements no method of hinting what format a library
|
||||||
|
should be linked with. When dynamically linking, the compiler will attempt to
|
||||||
|
maximize dynamic dependencies while still allowing some dependencies to be
|
||||||
|
linked in via an rlib.
|
||||||
|
|
||||||
|
For most situations, having all libraries available as a dylib is recommended
|
||||||
|
if dynamically linking. For other situations, the compiler will emit a
|
||||||
|
warning if it is unable to determine which formats to link each library with.
|
||||||
|
|
||||||
In general, `--crate-type=bin` or `--crate-type=lib` should be sufficient for
|
In general, `--crate-type=bin` or `--crate-type=lib` should be sufficient for
|
||||||
all compilation needs, and the other options are just available if more
|
all compilation needs, and the other options are just available if more
|
||||||
|
|
Loading…
Add table
Add a link
Reference in a new issue