# Libraries and Metadata

When the compiler sees a reference to an external crate, it needs to load some
information about that crate. This chapter gives an overview of that process,
and the supported file formats for crate libraries.

## Libraries

A crate dependency can be loaded from an `rlib`, `dylib`, or `rmeta` file. A
key point of these file formats is that they contain `rustc`-specific
[*metadata*](#metadata). This metadata allows the compiler to discover enough
information about the external crate to understand the items it contains,
which macros it exports, and *much* more.

### rlib

An `rlib` is an [archive file], which is similar to a tar file. This file
format is specific to `rustc`, and may change over time. This file contains:

* Object code, which is the result of code generation. This is used during
  regular linking. There is a separate `.o` file for each [codegen unit]. The
  codegen step can be skipped with the [`-C
  linker-plugin-lto`][linker-plugin-lto] CLI option, which means each `.o`
  file will only contain LLVM bitcode.
* [LLVM bitcode], which is a binary representation of LLVM's intermediate
  representation, which is embedded as a section in the `.o` files. This can
  be used for [Link Time Optimization] (LTO). This can be removed with the
  [`-C embed-bitcode=no`][embed-bitcode] CLI option to improve compile times
  and reduce disk space if LTO is not needed.
* `rustc` [metadata], in a file named `lib.rmeta`.
* A symbol table, which is essentially a list of symbols with offsets to the
  object files that contain that symbol. This is pretty standard for archive
  files.


### dylib

A `dylib` is a platform-specific shared library. It includes the `rustc`
[metadata] in a special link section called `.rustc`.

### rmeta

An `rmeta` file is a custom binary format that contains the [metadata] for the
crate. This file can be used for fast "checks" of a project by skipping all code
generation (as is done with `cargo check`), collecting enough information for
documentation (as is done with `cargo doc`), or for [pipelining](#pipelining).
This file is created if the [`--emit=metadata`][emit] CLI option is used.

`rmeta` files do not support linking, since they do not contain compiled
object files.


## Metadata

The metadata contains a wide swath of different elements. This guide will not go
into detail about every field it contains. You are encouraged to browse the
[`CrateRoot`] definition to get a sense of the different elements it contains.
Everything about metadata encoding and decoding is in the [`rustc_metadata`]
package.

Here are a few highlights of things it contains:

* The version of the `rustc` compiler. The compiler will refuse to load files
  from any other version.
* The [Strict Version Hash](#strict-version-hash) (SVH). This helps ensure the
  correct dependency is loaded.
* The [Stable Crate Id](#stable-crate-id). This is a hash used
  to identify crates.
* Information about all the source files in the library. This can be used for
  a variety of things, such as diagnostics pointing to sources in a
  dependency.
* Information about exported macros, traits, types, and items. Generally,
  anything that's needed to be known when a path references something inside a
  crate dependency.
* Encoded [MIR]. This is optional, and only encoded if needed for code
  generation. `cargo check` skips this for performance reasons.


### Strict Version Hash

The Strict Version Hash ([SVH], also known as the "crate hash") is a 64-bit
hash that is used to ensure that the correct crate dependencies are loaded. It
is possible for a directory to contain multiple copies of the same dependency
built with different settings, or built from different sources. The crate
loader will skip any crates that have the wrong SVH.