as( IDENTIFIER |
extern crate declaration specifies a dependency on an external crate.
The external crate is then bound into the declaring scope as the identifier
provided in the
extern crate declaration. Additionally, if the
extern crate appears in the crate root, then the crate name is also added to the
extern prelude, making it automatically in scope in all modules. The
clause can be used to bind the imported crate to a different name.
The external crate is resolved to a specific
soname at compile time, and a
runtime linkage requirement to that
soname is passed to the linker for
loading at runtime. The
soname is resolved at compile time by scanning the
compiler's library path and matching the optional
crate_name provided against
crate_name attributes that were declared on the external crate when it was
compiled. If no
crate_name is provided, a default
name attribute is assumed,
equal to the identifier given in the
extern crate declaration.
self crate may be imported which creates a binding to the current crate.
In this case the
as clause must be used to specify the name to bind it to.
Three examples of
extern crate declarations:
extern crate pcre; extern crate std; // equivalent to: extern crate std as std; extern crate std as ruststd; // linking to 'std' under another name
When naming Rust crates, hyphens are disallowed. However, Cargo packages may
make use of them. In such case, when
Cargo.toml doesn't specify a crate name,
Cargo will transparently replace
_ (Refer to RFC 940 for more
Here is an example:
// Importing the Cargo package hello-world extern crate hello_world; // hyphen replaced with an underscore
This section has been moved to Preludes — Extern Prelude.
An external crate dependency can be declared without binding its name in scope
by using an underscore with the form
extern crate foo as _. This may be
useful for crates that only need to be linked, but are never referenced, and
will avoid being reported as unused.
no_link attribute may be specified on an
extern crate item to
prevent linking the crate into the output. This is commonly used to load a
crate to access only its macros.