Extern crate declarations

^Syntax:
ExternCrate :
extern crate IDENTIFIER (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 ident provided in the extern_crate_decl.

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 ident given in the extern_crate_decl.

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