Extern crate declarations

^Syntax:
ExternCrate :
extern crate CrateRef AsClause^? ;

CrateRef :
IDENTIFIER | self

AsClause :
as ( IDENTIFIER | _ )

An 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. The as 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 crateid provided against the crateid attributes that were declared on the external crate when it was compiled. If no crateid is provided, a default name attribute is assumed, equal to the identifier given in the extern crate declaration.

The 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 - with _ (Refer to RFC 940 for more details).

Here is an example:

// Importing the Cargo package hello-world
extern crate hello_world; // hyphen replaced with an underscore

Extern Prelude

External crates imported with extern crate in the root module or provided to the compiler (as with the --extern flag with rustc) are added to the "extern prelude". Crates in the extern prelude are in scope in the entire crate, including inner modules. If imported with extern crate orig_name as new_name, then the symbol new_name is instead added to the prelude.

The core crate is always added to the extern prelude. The std crate is added as long as the no_std attribute is not specified in the crate root.

The no_implicit_prelude attribute can be used on a module to disable prelude lookups within that module.

Edition Differences: In the 2015 edition, crates in the extern prelude cannot be referenced via use declarations, so it is generally standard practice to include extern crate declarations to bring them into scope.

Beginning in the 2018 edition, use declarations can reference crates in the extern prelude, so it is considered unidiomatic to use extern crate.

Note: Additional crates that ship with rustc, such as alloc, and test, are not automatically included with the --extern flag when using Cargo. They must be brought into scope with an extern crate declaration, even in the 2018 edition.

#![allow(unused)]
fn main() {
extern crate alloc;
use alloc::rc::Rc;
}

Underscore Imports

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.

The macro_use attribute works as usual and import the macro names into the macro-use prelude.

The no_link attribute

The 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.