backend/libs-and-metadata.html - rust-lang/rustc-dev-guide - Git at Google

 <!DOCTYPE HTML>
 <html lang="en" class="light sidebar-visible" dir="ltr">
     <head>
         <!-- Book generated using mdBook -->
         <meta charset="UTF-8">
         <title>Libraries and metadata - Rust Compiler Development Guide</title>


         <!-- Custom HTML head -->

         <meta name="description" content="A guide to developing the Rust compiler (rustc)">
         <meta name="viewport" content="width=device-width, initial-scale=1">
         <meta name="theme-color" content="#ffffff">

         <link rel="icon" href="../favicon.svg">
         <link rel="shortcut icon" href="../favicon.png">
         <link rel="stylesheet" href="../css/variables.css">
         <link rel="stylesheet" href="../css/general.css">
         <link rel="stylesheet" href="../css/chrome.css">
         <link rel="stylesheet" href="../css/print.css" media="print">

         <!-- Fonts -->
         <link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
         <link rel="stylesheet" href="../fonts/fonts.css">

         <!-- Highlight.js Stylesheets -->
         <link rel="stylesheet" id="highlight-css" href="../highlight.css">
         <link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
         <link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">

         <!-- Custom theme stylesheets -->
         <link rel="stylesheet" href="../pagetoc.css">


         <!-- Provide site root and default themes to javascript -->
         <script>
             const path_to_root = "../";
             const default_light_theme = "light";
             const default_dark_theme = "navy";
             window.path_to_searchindex_js = "../searchindex.js";
         </script>
         <!-- Start loading toc.js asap -->
         <script src="../toc.js"></script>
     </head>
     <body>
     <div id="mdbook-help-container">
         <div id="mdbook-help-popup">
             <h2 class="mdbook-help-title">Keyboard shortcuts</h2>
             <div>
                 <p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
                 <p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
                 <p>Press <kbd>?</kbd> to show this help</p>
                 <p>Press <kbd>Esc</kbd> to hide this help</p>
             </div>
         </div>
     </div>
     <div id="body-container">
         <!-- Work around some values being stored in localStorage wrapped in quotes -->
         <script>
             try {
                 let theme = localStorage.getItem('mdbook-theme');
                 let sidebar = localStorage.getItem('mdbook-sidebar');

                 if (theme.startsWith('"') && theme.endsWith('"')) {
                     localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
                 }

                 if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
                     localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
                 }
             } catch (e) { }
         </script>

         <!-- Set the theme before any content is loaded, prevents flash -->
         <script>
             const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
             let theme;
             try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
             if (theme === null || theme === undefined) { theme = default_theme; }
             const html = document.documentElement;
             html.classList.remove('light')
             html.classList.add(theme);
             html.classList.add("js");
         </script>

         <input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

         <!-- Hide / unhide sidebar before it is displayed -->
         <script>
             let sidebar = null;
             const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
             if (document.body.clientWidth >= 1080) {
                 try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
                 sidebar = sidebar || 'visible';
             } else {
                 sidebar = 'hidden';
                 sidebar_toggle.checked = false;
             }
             if (sidebar === 'visible') {
                 sidebar_toggle.checked = true;
             } else {
                 html.classList.remove('sidebar-visible');
             }
         </script>

         <nav id="sidebar" class="sidebar" aria-label="Table of contents">
             <!-- populated by js -->
             <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
             <noscript>
                 <iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
             </noscript>
             <div id="sidebar-resize-handle" class="sidebar-resize-handle">
                 <div class="sidebar-resize-indicator"></div>
             </div>
         </nav>

         <div id="page-wrapper" class="page-wrapper">

             <div class="page">
                 <div id="menu-bar-hover-placeholder"></div>
                 <div id="menu-bar" class="menu-bar sticky">
                     <div class="left-buttons">
                         <label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
                             <i class="fa fa-bars"></i>
                         </label>
                         <button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
                             <i class="fa fa-paint-brush"></i>
                         </button>
                         <ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
                             <li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
                             <li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
                         </ul>
                         <button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
                             <i class="fa fa-search"></i>
                         </button>
                     </div>

                     <h1 class="menu-title">Rust Compiler Development Guide</h1>

                     <div class="right-buttons">
                         <a href="../print.html" title="Print this book" aria-label="Print this book">
                             <i id="print-button" class="fa fa-print"></i>
                         </a>
                         <a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
                             <i id="git-repository-button" class="fa fa-github"></i>
                         </a>
                         <a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/backend/libs-and-metadata.md" title="Suggest an edit" aria-label="Suggest an edit" rel="edit">
                             <i id="git-edit-button" class="fa fa-edit"></i>
                         </a>

                     </div>
                 </div>

                 <div id="search-wrapper" class="hidden">
                     <form id="searchbar-outer" class="searchbar-outer">
                         <div class="search-wrapper">
                             <input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
                             <div class="spinner-wrapper">
                                 <i class="fa fa-spinner fa-spin"></i>
                             </div>
                         </div>
                     </form>
                     <div id="searchresults-outer" class="searchresults-outer hidden">
                         <div id="searchresults-header" class="searchresults-header"></div>
                         <ul id="searchresults">
                         </ul>
                     </div>
                 </div>

                 <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
                 <script>
                     document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
                     document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
                     Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
                         link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
                     });
                 </script>

                 <div id="content" class="content">
                     <main>
                         <h1 id="libraries-and-metadata"><a class="header" href="#libraries-and-metadata">Libraries and metadata</a></h1>
 <p>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.</p>
 <h2 id="libraries"><a class="header" href="#libraries">Libraries</a></h2>
 <p>A crate dependency can be loaded from an <code>rlib</code>, <code>dylib</code>, or <code>rmeta</code> file. A
 key point of these file formats is that they contain <code>rustc</code>-specific
 <a href="#metadata"><em>metadata</em></a>. This metadata allows the compiler to discover enough
 information about the external crate to understand the items it contains,
 which macros it exports, and <em>much</em> more.</p>
 <h3 id="rlib"><a class="header" href="#rlib">rlib</a></h3>
 <p>An <code>rlib</code> is an <a href="https://en.wikipedia.org/wiki/Ar_(Unix)">archive file</a>, which is similar to a tar file. This file
 format is specific to <code>rustc</code>, and may change over time. This file contains:</p>
 <ul>
 <li>Object code, which is the result of code generation. This is used during
 regular linking. There is a separate <code>.o</code> file for each <a href="../backend/codegen.html">codegen unit</a>. The
 codegen step can be skipped with the <a href="https://doc.rust-lang.org/rustc/codegen-options/index.html#linker-plugin-lto"><code>-C linker-plugin-lto</code></a> CLI option, which means each <code>.o</code>
 file will only contain LLVM bitcode.</li>
 <li><a href="https://llvm.org/docs/BitCodeFormat.html">LLVM bitcode</a>, which is a binary representation of LLVM's intermediate
 representation, which is embedded as a section in the <code>.o</code> files. This can
 be used for <a href="https://llvm.org/docs/LinkTimeOptimization.html">Link Time Optimization</a> (LTO). This can be removed with the
 <a href="https://doc.rust-lang.org/rustc/codegen-options/index.html#embed-bitcode"><code>-C embed-bitcode=no</code></a> CLI option to improve compile times
 and reduce disk space if LTO is not needed.</li>
 <li><code>rustc</code> <a href="#metadata">metadata</a>, in a file named <code>lib.rmeta</code>.</li>
 <li>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.</li>
 </ul>
 <h3 id="dylib"><a class="header" href="#dylib">dylib</a></h3>
 <p>A <code>dylib</code> is a platform-specific shared library. It includes the <code>rustc</code>
 <a href="#metadata">metadata</a> in a special link section called <code>.rustc</code>.</p>
 <h3 id="rmeta"><a class="header" href="#rmeta">rmeta</a></h3>
 <p>An <code>rmeta</code> file is a custom binary format that contains the <a href="#metadata">metadata</a> for the
 crate. This file can be used for fast "checks" of a project by skipping all code
 generation (as is done with <code>cargo check</code>), collecting enough information for
 documentation (as is done with <code>cargo doc</code>), or for <a href="#pipelining">pipelining</a>.
 This file is created if the <a href="https://doc.rust-lang.org/rustc/command-line-arguments.html#option-emit"><code>--emit=metadata</code></a> CLI option is used.</p>
 <p><code>rmeta</code> files do not support linking, since they do not contain compiled
 object files.</p>
 <h2 id="metadata"><a class="header" href="#metadata">Metadata</a></h2>
 <p>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
 <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/struct.CrateRoot.html"><code>CrateRoot</code></a> definition to get a sense of the different elements it contains.
 Everything about metadata encoding and decoding is in the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/index.html"><code>rustc_metadata</code></a>
 package.</p>
 <p>Here are a few highlights of things it contains:</p>
 <ul>
 <li>The version of the <code>rustc</code> compiler. The compiler will refuse to load files
 from any other version.</li>
 <li>The <a href="#strict-version-hash">Strict Version Hash</a> (SVH). This helps ensure the
 correct dependency is loaded.</li>
 <li>The <a href="#stable-crate-id">Stable Crate Id</a>. This is a hash used
 to identify crates.</li>
 <li>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.</li>
 <li>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.</li>
 <li>Encoded <a href="../mir/index.html">MIR</a>. This is optional, and only encoded if needed for code
 generation. <code>cargo check</code> skips this for performance reasons.</li>
 </ul>
 <h3 id="strict-version-hash"><a class="header" href="#strict-version-hash">Strict Version Hash</a></h3>
 <p>The Strict Version Hash (<a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/svh/struct.Svh.html">SVH</a>, 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.</p>
 <p>The SVH is also used for the <a href="../queries/incremental-compilation.html">incremental compilation</a> session filename,
 though that usage is mostly historic.</p>
 <p>The hash includes a variety of elements:</p>
 <ul>
 <li>Hashes of the HIR nodes.</li>
 <li>All of the upstream crate hashes.</li>
 <li>All of the source filenames.</li>
 <li>Hashes of certain command-line flags (like <code>-C metadata</code> via the <a href="#stable-crate-id">Stable
 Crate Id</a>, and all CLI options marked with <code>[TRACKED]</code>).</li>
 </ul>
 <p>See <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast_lowering/fn.compute_hir_hash.html"><code>compute_hir_hash</code></a> for where the hash is actually computed.</p>
 <h3 id="stable-crate-id"><a class="header" href="#stable-crate-id">Stable Crate Id</a></h3>
 <p>The <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/def_id/struct.StableCrateId.html"><code>StableCrateId</code></a> is a 64-bit hash used to identify different crates with
 potentially the same name. It is a hash of the crate name and all the
 <a href="https://doc.rust-lang.org/rustc/codegen-options/index.html#metadata"><code>-C metadata</code></a> CLI options computed in <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/def_id/struct.StableCrateId.html#method.new"><code>StableCrateId::new</code></a>. It is
 used in a variety of places, such as symbol name mangling, crate loading, and
 much more.</p>
 <p>By default, all Rust symbols are mangled and incorporate the stable crate id.
 This allows multiple versions of the same crate to be included together. Cargo
 automatically generates <code>-C metadata</code> hashes based on a variety of factors, like
 the package version, source, and target kind (a lib and test can have the same
 crate name, so they need to be disambiguated).</p>
 <h2 id="crate-loading"><a class="header" href="#crate-loading">Crate loading</a></h2>
 <p>Crate loading can have quite a few subtle complexities. During <a href="../name-resolution.html">name
 resolution</a>, when an external crate is referenced (via an <code>extern crate</code> or
 path), the resolver uses the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/creader/struct.CrateLoader.html"><code>CrateLoader</code></a> which is responsible for finding
 the crate libraries and loading the <a href="#metadata">metadata</a> for them. After the dependency
 is loaded, the <code>CrateLoader</code> will provide the information the resolver needs
 to perform its job (such as expanding macros, resolving paths, etc.).</p>
 <p>To load each external crate, the <code>CrateLoader</code> uses a <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/locator/struct.CrateLocator.html"><code>CrateLocator</code></a> to
 actually find the correct files for one specific crate. There is some great
 documentation in the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/locator/index.html"><code>locator</code></a> module that goes into detail on how loading
 works, and I strongly suggest reading it to get the full picture.</p>
 <p>The location of a dependency can come from several different places. Direct
 dependencies are usually passed with <code>--extern</code> flags, and the loader can look
 at those directly. Direct dependencies often have references to their own
 dependencies, which need to be loaded, too. These are usually found by
 scanning the directories passed with the <code>-L</code> flag for any file whose metadata
 contains a matching crate name and <a href="#strict-version-hash">SVH</a>. The loader
 will also look at the <a href="../building/bootstrapping/what-bootstrapping-does.html#what-is-a-sysroot">sysroot</a> to find dependencies.</p>
 <p>As crates are loaded, they are kept in the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/creader/struct.CStore.html"><code>CStore</code></a> with the crate metadata
 wrapped in the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/decoder/struct.CrateMetadata.html"><code>CrateMetadata</code></a> struct. After resolution and expansion, the
 <code>CStore</code> will make its way into the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.GlobalCtxt.html"><code>GlobalCtxt</code></a> for the rest of the
 compilation.</p>
 <h2 id="pipelining"><a class="header" href="#pipelining">Pipelining</a></h2>
 <p>One trick to improve compile times is to start building a crate as soon as the
 metadata for its dependencies is available. For a library, there is no need to
 wait for the code generation of dependencies to finish. Cargo implements this
 technique by telling <code>rustc</code> to emit an <a href="#rmeta"><code>rmeta</code></a> file for each
 dependency as well as an <a href="#rlib"><code>rlib</code></a>. As early as it can, <code>rustc</code> will
 save the <code>rmeta</code> file to disk before it continues to the code generation
 phase. The compiler sends a JSON message to let the build tool know that it
 can start building the next crate if possible.</p>
 <p>The <a href="#crate-loading">crate loading</a> system is smart enough to know when it
 sees an <code>rmeta</code> file to use that if the <code>rlib</code> is not there (or has only been
 partially written).</p>
 <p>This pipelining isn't possible for binaries, because the linking phase will
 require the code generation of all its dependencies. In the future, it may be
 possible to further improve this scenario by splitting linking into a separate
 command (see <a href="https://github.com/rust-lang/rust/issues/64191">#64191</a>).</p>

                     </main>

                     <nav class="nav-wrapper" aria-label="Page navigation">
                         <!-- Mobile navigation buttons -->
                             <a rel="prev" href="../backend/implicit-caller-location.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                                 <i class="fa fa-angle-left"></i>
                             </a>

                             <a rel="next prefetch" href="../profile-guided-optimization.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                                 <i class="fa fa-angle-right"></i>
                             </a>

                         <div style="clear: both"></div>
                     </nav>
                 </div>
             </div>

             <nav class="nav-wide-wrapper" aria-label="Page navigation">
                     <a rel="prev" href="../backend/implicit-caller-location.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
                         <i class="fa fa-angle-left"></i>
                     </a>

                     <a rel="next prefetch" href="../profile-guided-optimization.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
                         <i class="fa fa-angle-right"></i>
                     </a>
             </nav>

         </div>


         <script>
             window.playground_copyable = true;
         </script>


         <script src="../elasticlunr.min.js"></script>
         <script src="../mark.min.js"></script>
         <script src="../searcher.js"></script>

         <script src="../clipboard.min.js"></script>
         <script src="../highlight.js"></script>
         <script src="../book.js"></script>

         <!-- Custom JS scripts -->
         <script src="../mermaid.min.js"></script>
         <script src="../mermaid-init.js"></script>
         <script src="../pagetoc.js"></script>


     </div>
     </body>
 </html>
	<!DOCTYPE HTML>
	<html lang="en" class="light sidebar-visible" dir="ltr">
	<head>
	<!-- Book generated using mdBook -->
	<meta charset="UTF-8">
	<title>Libraries and metadata - Rust Compiler Development Guide</title>


	<!-- Custom HTML head -->

	<meta name="description" content="A guide to developing the Rust compiler (rustc)">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<meta name="theme-color" content="#ffffff">

	<link rel="icon" href="../favicon.svg">
	<link rel="shortcut icon" href="../favicon.png">
	<link rel="stylesheet" href="../css/variables.css">
	<link rel="stylesheet" href="../css/general.css">
	<link rel="stylesheet" href="../css/chrome.css">
	<link rel="stylesheet" href="../css/print.css" media="print">

	<!-- Fonts -->
	<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
	<link rel="stylesheet" href="../fonts/fonts.css">

	<!-- Highlight.js Stylesheets -->
	<link rel="stylesheet" id="highlight-css" href="../highlight.css">
	<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
	<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">

	<!-- Custom theme stylesheets -->
	<link rel="stylesheet" href="../pagetoc.css">


	<!-- Provide site root and default themes to javascript -->
	<script>
	const path_to_root = "../";
	const default_light_theme = "light";
	const default_dark_theme = "navy";
	window.path_to_searchindex_js = "../searchindex.js";
	</script>
	<!-- Start loading toc.js asap -->
	<script src="../toc.js"></script>
	</head>
	<body>
	<div id="mdbook-help-container">
	<div id="mdbook-help-popup">
	<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
	<div>
	<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
	<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
	<p>Press <kbd>?</kbd> to show this help</p>
	<p>Press <kbd>Esc</kbd> to hide this help</p>
	</div>
	</div>
	</div>
	<div id="body-container">
	<!-- Work around some values being stored in localStorage wrapped in quotes -->
	<script>
	try {
	let theme = localStorage.getItem('mdbook-theme');
	let sidebar = localStorage.getItem('mdbook-sidebar');

	if (theme.startsWith('"') && theme.endsWith('"')) {
	localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
	}

	if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
	localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
	}
	} catch (e) { }
	</script>

	<!-- Set the theme before any content is loaded, prevents flash -->
	<script>
	const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
	let theme;
	try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
	if (theme === null \|\| theme === undefined) { theme = default_theme; }
	const html = document.documentElement;
	html.classList.remove('light')
	html.classList.add(theme);
	html.classList.add("js");
	</script>

	<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">

	<!-- Hide / unhide sidebar before it is displayed -->
	<script>
	let sidebar = null;
	const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
	if (document.body.clientWidth >= 1080) {
	try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
	sidebar = sidebar \|\| 'visible';
	} else {
	sidebar = 'hidden';
	sidebar_toggle.checked = false;
	}
	if (sidebar === 'visible') {
	sidebar_toggle.checked = true;
	} else {
	html.classList.remove('sidebar-visible');
	}
	</script>

	<nav id="sidebar" class="sidebar" aria-label="Table of contents">
	<!-- populated by js -->
	<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
	<noscript>
	<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
	</noscript>
	<div id="sidebar-resize-handle" class="sidebar-resize-handle">
	<div class="sidebar-resize-indicator"></div>
	</div>
	</nav>

	<div id="page-wrapper" class="page-wrapper">

	<div class="page">
	<div id="menu-bar-hover-placeholder"></div>
	<div id="menu-bar" class="menu-bar sticky">
	<div class="left-buttons">
	<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
	<i class="fa fa-bars"></i>
	</label>
	<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
	<i class="fa fa-paint-brush"></i>
	</button>
	<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
	<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
	<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
	<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
	<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
	<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
	<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
	</ul>
	<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
	<i class="fa fa-search"></i>
	</button>
	</div>

	<h1 class="menu-title">Rust Compiler Development Guide</h1>

	<div class="right-buttons">
	<a href="../print.html" title="Print this book" aria-label="Print this book">
	<i id="print-button" class="fa fa-print"></i>
	</a>
	<a href="https://github.com/rust-lang/rustc-dev-guide" title="Git repository" aria-label="Git repository">
	<i id="git-repository-button" class="fa fa-github"></i>
	</a>
	<a href="https://github.com/rust-lang/rustc-dev-guide/edit/master/src/backend/libs-and-metadata.md" title="Suggest an edit" aria-label="Suggest an edit" rel="edit">
	<i id="git-edit-button" class="fa fa-edit"></i>
	</a>

	</div>
	</div>

	<div id="search-wrapper" class="hidden">
	<form id="searchbar-outer" class="searchbar-outer">
	<div class="search-wrapper">
	<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
	<div class="spinner-wrapper">
	<i class="fa fa-spinner fa-spin"></i>
	</div>
	</div>
	</form>
	<div id="searchresults-outer" class="searchresults-outer hidden">
	<div id="searchresults-header" class="searchresults-header"></div>
	<ul id="searchresults">
	</ul>
	</div>
	</div>

	<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
	<script>
	document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
	document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
	Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
	link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
	});
	</script>

	<div id="content" class="content">
	<main>
	<h1 id="libraries-and-metadata"><a class="header" href="#libraries-and-metadata">Libraries and metadata</a></h1>
	<p>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.</p>
	<h2 id="libraries"><a class="header" href="#libraries">Libraries</a></h2>
	<p>A crate dependency can be loaded from an <code>rlib</code>, <code>dylib</code>, or <code>rmeta</code> file. A
	key point of these file formats is that they contain <code>rustc</code>-specific
	<a href="#metadata"><em>metadata</em></a>. This metadata allows the compiler to discover enough
	information about the external crate to understand the items it contains,
	which macros it exports, and <em>much</em> more.</p>
	<h3 id="rlib"><a class="header" href="#rlib">rlib</a></h3>
	<p>An <code>rlib</code> is an <a href="https://en.wikipedia.org/wiki/Ar_(Unix)">archive file</a>, which is similar to a tar file. This file
	format is specific to <code>rustc</code>, and may change over time. This file contains:</p>
	<ul>
	<li>Object code, which is the result of code generation. This is used during
	regular linking. There is a separate <code>.o</code> file for each <a href="../backend/codegen.html">codegen unit</a>. The
	codegen step can be skipped with the <a href="https://doc.rust-lang.org/rustc/codegen-options/index.html#linker-plugin-lto"><code>-C linker-plugin-lto</code></a> CLI option, which means each <code>.o</code>
	file will only contain LLVM bitcode.</li>
	<li><a href="https://llvm.org/docs/BitCodeFormat.html">LLVM bitcode</a>, which is a binary representation of LLVM's intermediate
	representation, which is embedded as a section in the <code>.o</code> files. This can
	be used for <a href="https://llvm.org/docs/LinkTimeOptimization.html">Link Time Optimization</a> (LTO). This can be removed with the
	<a href="https://doc.rust-lang.org/rustc/codegen-options/index.html#embed-bitcode"><code>-C embed-bitcode=no</code></a> CLI option to improve compile times
	and reduce disk space if LTO is not needed.</li>
	<li><code>rustc</code> <a href="#metadata">metadata</a>, in a file named <code>lib.rmeta</code>.</li>
	<li>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.</li>
	</ul>
	<h3 id="dylib"><a class="header" href="#dylib">dylib</a></h3>
	<p>A <code>dylib</code> is a platform-specific shared library. It includes the <code>rustc</code>
	<a href="#metadata">metadata</a> in a special link section called <code>.rustc</code>.</p>
	<h3 id="rmeta"><a class="header" href="#rmeta">rmeta</a></h3>
	<p>An <code>rmeta</code> file is a custom binary format that contains the <a href="#metadata">metadata</a> for the
	crate. This file can be used for fast "checks" of a project by skipping all code
	generation (as is done with <code>cargo check</code>), collecting enough information for
	documentation (as is done with <code>cargo doc</code>), or for <a href="#pipelining">pipelining</a>.
	This file is created if the <a href="https://doc.rust-lang.org/rustc/command-line-arguments.html#option-emit"><code>--emit=metadata</code></a> CLI option is used.</p>
	<p><code>rmeta</code> files do not support linking, since they do not contain compiled
	object files.</p>
	<h2 id="metadata"><a class="header" href="#metadata">Metadata</a></h2>
	<p>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
	<a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/struct.CrateRoot.html"><code>CrateRoot</code></a> definition to get a sense of the different elements it contains.
	Everything about metadata encoding and decoding is in the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/index.html"><code>rustc_metadata</code></a>
	package.</p>
	<p>Here are a few highlights of things it contains:</p>
	<ul>
	<li>The version of the <code>rustc</code> compiler. The compiler will refuse to load files
	from any other version.</li>
	<li>The <a href="#strict-version-hash">Strict Version Hash</a> (SVH). This helps ensure the
	correct dependency is loaded.</li>
	<li>The <a href="#stable-crate-id">Stable Crate Id</a>. This is a hash used
	to identify crates.</li>
	<li>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.</li>
	<li>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.</li>
	<li>Encoded <a href="../mir/index.html">MIR</a>. This is optional, and only encoded if needed for code
	generation. <code>cargo check</code> skips this for performance reasons.</li>
	</ul>
	<h3 id="strict-version-hash"><a class="header" href="#strict-version-hash">Strict Version Hash</a></h3>
	<p>The Strict Version Hash (<a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_data_structures/svh/struct.Svh.html">SVH</a>, 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.</p>
	<p>The SVH is also used for the <a href="../queries/incremental-compilation.html">incremental compilation</a> session filename,
	though that usage is mostly historic.</p>
	<p>The hash includes a variety of elements:</p>
	<ul>
	<li>Hashes of the HIR nodes.</li>
	<li>All of the upstream crate hashes.</li>
	<li>All of the source filenames.</li>
	<li>Hashes of certain command-line flags (like <code>-C metadata</code> via the <a href="#stable-crate-id">Stable
	Crate Id</a>, and all CLI options marked with <code>[TRACKED]</code>).</li>
	</ul>
	<p>See <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_ast_lowering/fn.compute_hir_hash.html"><code>compute_hir_hash</code></a> for where the hash is actually computed.</p>
	<h3 id="stable-crate-id"><a class="header" href="#stable-crate-id">Stable Crate Id</a></h3>
	<p>The <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/def_id/struct.StableCrateId.html"><code>StableCrateId</code></a> is a 64-bit hash used to identify different crates with
	potentially the same name. It is a hash of the crate name and all the
	<a href="https://doc.rust-lang.org/rustc/codegen-options/index.html#metadata"><code>-C metadata</code></a> CLI options computed in <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/def_id/struct.StableCrateId.html#method.new"><code>StableCrateId::new</code></a>. It is
	used in a variety of places, such as symbol name mangling, crate loading, and
	much more.</p>
	<p>By default, all Rust symbols are mangled and incorporate the stable crate id.
	This allows multiple versions of the same crate to be included together. Cargo
	automatically generates <code>-C metadata</code> hashes based on a variety of factors, like
	the package version, source, and target kind (a lib and test can have the same
	crate name, so they need to be disambiguated).</p>
	<h2 id="crate-loading"><a class="header" href="#crate-loading">Crate loading</a></h2>
	<p>Crate loading can have quite a few subtle complexities. During <a href="../name-resolution.html">name
	resolution</a>, when an external crate is referenced (via an <code>extern crate</code> or
	path), the resolver uses the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/creader/struct.CrateLoader.html"><code>CrateLoader</code></a> which is responsible for finding
	the crate libraries and loading the <a href="#metadata">metadata</a> for them. After the dependency
	is loaded, the <code>CrateLoader</code> will provide the information the resolver needs
	to perform its job (such as expanding macros, resolving paths, etc.).</p>
	<p>To load each external crate, the <code>CrateLoader</code> uses a <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/locator/struct.CrateLocator.html"><code>CrateLocator</code></a> to
	actually find the correct files for one specific crate. There is some great
	documentation in the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/locator/index.html"><code>locator</code></a> module that goes into detail on how loading
	works, and I strongly suggest reading it to get the full picture.</p>
	<p>The location of a dependency can come from several different places. Direct
	dependencies are usually passed with <code>--extern</code> flags, and the loader can look
	at those directly. Direct dependencies often have references to their own
	dependencies, which need to be loaded, too. These are usually found by
	scanning the directories passed with the <code>-L</code> flag for any file whose metadata
	contains a matching crate name and <a href="#strict-version-hash">SVH</a>. The loader
	will also look at the <a href="../building/bootstrapping/what-bootstrapping-does.html#what-is-a-sysroot">sysroot</a> to find dependencies.</p>
	<p>As crates are loaded, they are kept in the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/creader/struct.CStore.html"><code>CStore</code></a> with the crate metadata
	wrapped in the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_metadata/rmeta/decoder/struct.CrateMetadata.html"><code>CrateMetadata</code></a> struct. After resolution and expansion, the
	<code>CStore</code> will make its way into the <a href="https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.GlobalCtxt.html"><code>GlobalCtxt</code></a> for the rest of the
	compilation.</p>
	<h2 id="pipelining"><a class="header" href="#pipelining">Pipelining</a></h2>
	<p>One trick to improve compile times is to start building a crate as soon as the
	metadata for its dependencies is available. For a library, there is no need to
	wait for the code generation of dependencies to finish. Cargo implements this
	technique by telling <code>rustc</code> to emit an <a href="#rmeta"><code>rmeta</code></a> file for each
	dependency as well as an <a href="#rlib"><code>rlib</code></a>. As early as it can, <code>rustc</code> will
	save the <code>rmeta</code> file to disk before it continues to the code generation
	phase. The compiler sends a JSON message to let the build tool know that it
	can start building the next crate if possible.</p>
	<p>The <a href="#crate-loading">crate loading</a> system is smart enough to know when it
	sees an <code>rmeta</code> file to use that if the <code>rlib</code> is not there (or has only been
	partially written).</p>
	<p>This pipelining isn't possible for binaries, because the linking phase will
	require the code generation of all its dependencies. In the future, it may be
	possible to further improve this scenario by splitting linking into a separate
	command (see <a href="https://github.com/rust-lang/rust/issues/64191">#64191</a>).</p>

	</main>

	<nav class="nav-wrapper" aria-label="Page navigation">
	<!-- Mobile navigation buttons -->
	<a rel="prev" href="../backend/implicit-caller-location.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
	<i class="fa fa-angle-left"></i>
	</a>

	<a rel="next prefetch" href="../profile-guided-optimization.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
	<i class="fa fa-angle-right"></i>
	</a>

	<div style="clear: both"></div>
	</nav>
	</div>
	</div>

	<nav class="nav-wide-wrapper" aria-label="Page navigation">
	<a rel="prev" href="../backend/implicit-caller-location.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
	<i class="fa fa-angle-left"></i>
	</a>

	<a rel="next prefetch" href="../profile-guided-optimization.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
	<i class="fa fa-angle-right"></i>
	</a>
	</nav>

	</div>




	<script>
	window.playground_copyable = true;
	</script>


	<script src="../elasticlunr.min.js"></script>
	<script src="../mark.min.js"></script>
	<script src="../searcher.js"></script>

	<script src="../clipboard.min.js"></script>
	<script src="../highlight.js"></script>
	<script src="../book.js"></script>

	<!-- Custom JS scripts -->
	<script src="../mermaid.min.js"></script>
	<script src="../mermaid-init.js"></script>
	<script src="../pagetoc.js"></script>



	</div>
	</body>
	</html>