<!DOCTYPE HTML> <html lang="en"> <head> <meta charset="UTF-8"> <title>Linkage - The Rust Reference</title> <meta content="text/html; charset=utf-8" http-equiv="Content-Type"> <meta name="description" content=""> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="theme-color" content="#ffffff" /> <base href=""> <link rel="stylesheet" href="book.css"> <link href="https://fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet" type="text/css"> <link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:500" rel="stylesheet" type="text/css"> <link rel="shortcut icon" href="favicon.png"> <!-- Font Awesome --> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css"> <link rel="stylesheet" href="highlight.css"> <link rel="stylesheet" href="tomorrow-night.css"> <link rel="stylesheet" href="ayu-highlight.css"> <!-- Custom theme --> <link rel="stylesheet" href="src/theme/reference.css"> <!-- Fetch Clipboard.js from CDN but have a local fallback --> <script src="https://cdn.jsdelivr.net/clipboard.js/1.6.1/clipboard.min.js"></script> <script> if (typeof Clipboard == 'undefined') { document.write(unescape("%3Cscript src='clipboard.min.js'%3E%3C/script%3E")); } </script> </head> <body class="light"> <!-- Work around some values being stored in localStorage wrapped in quotes --> <script type="text/javascript"> try { var theme = localStorage.getItem('mdbook-theme'); var 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 type="text/javascript"> var theme; try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { } if (theme === null || theme === undefined) { theme = 'light'; } document.body.className = theme; document.querySelector('html').className = theme; </script> <!-- Hide / unhide sidebar before it is displayed --> <script type="text/javascript"> var sidebar = 'hidden'; if (document.body.clientWidth >= 1080) { try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { } sidebar = sidebar || 'visible'; } document.querySelector('html').classList.add("sidebar-" + sidebar); </script> <nav id="sidebar" class="sidebar" aria-label="Table of contents"> <ol class="chapter"><li class="affix"><a href="introduction.html">Introduction</a></li><li><a href="notation.html"><strong aria-hidden="true">1.</strong> Notation</a></li><li><a href="lexical-structure.html"><strong aria-hidden="true">2.</strong> Lexical structure</a></li><li><ol class="section"><li><a href="input-format.html"><strong aria-hidden="true">2.1.</strong> Input format</a></li><li><a href="keywords.html"><strong aria-hidden="true">2.2.</strong> Keywords</a></li><li><a href="identifiers.html"><strong aria-hidden="true">2.3.</strong> Identifiers</a></li><li><a href="comments.html"><strong aria-hidden="true">2.4.</strong> Comments</a></li><li><a href="whitespace.html"><strong aria-hidden="true">2.5.</strong> Whitespace</a></li><li><a href="tokens.html"><strong aria-hidden="true">2.6.</strong> Tokens</a></li><li><a href="paths.html"><strong aria-hidden="true">2.7.</strong> Paths</a></li></ol></li><li><a href="macros.html"><strong aria-hidden="true">3.</strong> Macros</a></li><li><ol class="section"><li><a href="macros-by-example.html"><strong aria-hidden="true">3.1.</strong> Macros By Example</a></li><li><a href="procedural-macros.html"><strong aria-hidden="true">3.2.</strong> Procedural Macros</a></li></ol></li><li><a href="crates-and-source-files.html"><strong aria-hidden="true">4.</strong> Crates and source files</a></li><li><a href="items-and-attributes.html"><strong aria-hidden="true">5.</strong> Items and attributes</a></li><li><ol class="section"><li><a href="items.html"><strong aria-hidden="true">5.1.</strong> Items</a></li><li><ol class="section"><li><a href="items/modules.html"><strong aria-hidden="true">5.1.1.</strong> Modules</a></li><li><a href="items/extern-crates.html"><strong aria-hidden="true">5.1.2.</strong> Extern crates</a></li><li><a href="items/use-declarations.html"><strong aria-hidden="true">5.1.3.</strong> Use declarations</a></li><li><a href="items/functions.html"><strong aria-hidden="true">5.1.4.</strong> Functions</a></li><li><a href="items/type-aliases.html"><strong aria-hidden="true">5.1.5.</strong> Type aliases</a></li><li><a href="items/structs.html"><strong aria-hidden="true">5.1.6.</strong> Structs</a></li><li><a href="items/enumerations.html"><strong aria-hidden="true">5.1.7.</strong> Enumerations</a></li><li><a href="items/unions.html"><strong aria-hidden="true">5.1.8.</strong> Unions</a></li><li><a href="items/constant-items.html"><strong aria-hidden="true">5.1.9.</strong> Constant items</a></li><li><a href="items/static-items.html"><strong aria-hidden="true">5.1.10.</strong> Static items</a></li><li><a href="items/traits.html"><strong aria-hidden="true">5.1.11.</strong> Traits</a></li><li><a href="items/implementations.html"><strong aria-hidden="true">5.1.12.</strong> Implementations</a></li><li><a href="items/external-blocks.html"><strong aria-hidden="true">5.1.13.</strong> External blocks</a></li></ol></li><li><a href="visibility-and-privacy.html"><strong aria-hidden="true">5.2.</strong> Visibility and Privacy</a></li><li><a href="attributes.html"><strong aria-hidden="true">5.3.</strong> Attributes</a></li></ol></li><li><a href="statements-and-expressions.html"><strong aria-hidden="true">6.</strong> Statements and expressions</a></li><li><ol class="section"><li><a href="statements.html"><strong aria-hidden="true">6.1.</strong> Statements</a></li><li><a href="expressions.html"><strong aria-hidden="true">6.2.</strong> Expressions</a></li><li><ol class="section"><li><a href="expressions/literal-expr.html"><strong aria-hidden="true">6.2.1.</strong> Literal expressions</a></li><li><a href="expressions/path-expr.html"><strong aria-hidden="true">6.2.2.</strong> Path expressions</a></li><li><a href="expressions/block-expr.html"><strong aria-hidden="true">6.2.3.</strong> Block expressions</a></li><li><a href="expressions/operator-expr.html"><strong aria-hidden="true">6.2.4.</strong> Operator expressions</a></li><li><a href="expressions/array-expr.html"><strong aria-hidden="true">6.2.5.</strong> Array and index expressions</a></li><li><a href="expressions/tuple-expr.html"><strong aria-hidden="true">6.2.6.</strong> Tuple and index expressions</a></li><li><a href="expressions/struct-expr.html"><strong aria-hidden="true">6.2.7.</strong> Struct expressions</a></li><li><a href="expressions/enum-variant-expr.html"><strong aria-hidden="true">6.2.8.</strong> Enum variant expressions</a></li><li><a href="expressions/call-expr.html"><strong aria-hidden="true">6.2.9.</strong> Call expressions</a></li><li><a href="expressions/method-call-expr.html"><strong aria-hidden="true">6.2.10.</strong> Method call expressions</a></li><li><a href="expressions/field-expr.html"><strong aria-hidden="true">6.2.11.</strong> Field access expressions</a></li><li><a href="expressions/closure-expr.html"><strong aria-hidden="true">6.2.12.</strong> Closure expressions</a></li><li><a href="expressions/loop-expr.html"><strong aria-hidden="true">6.2.13.</strong> Loop expressions</a></li><li><a href="expressions/range-expr.html"><strong aria-hidden="true">6.2.14.</strong> Range expressions</a></li><li><a href="expressions/if-expr.html"><strong aria-hidden="true">6.2.15.</strong> If and if let expressions</a></li><li><a href="expressions/match-expr.html"><strong aria-hidden="true">6.2.16.</strong> Match expressions</a></li><li><a href="expressions/return-expr.html"><strong aria-hidden="true">6.2.17.</strong> Return expressions</a></li></ol></li></ol></li><li><a href="type-system.html"><strong aria-hidden="true">7.</strong> Type system</a></li><li><ol class="section"><li><a href="types.html"><strong aria-hidden="true">7.1.</strong> Types</a></li><li><a href="dynamically-sized-types.html"><strong aria-hidden="true">7.2.</strong> Dynamically Sized Types</a></li><li><a href="type-layout.html"><strong aria-hidden="true">7.3.</strong> Type layout</a></li><li><a href="interior-mutability.html"><strong aria-hidden="true">7.4.</strong> Interior mutability</a></li><li><a href="subtyping.html"><strong aria-hidden="true">7.5.</strong> Subtyping</a></li><li><a href="type-coercions.html"><strong aria-hidden="true">7.6.</strong> Type coercions</a></li><li><a href="destructors.html"><strong aria-hidden="true">7.7.</strong> Destructors</a></li></ol></li><li><a href="special-types-and-traits.html"><strong aria-hidden="true">8.</strong> Special types and traits</a></li><li><a href="memory-model.html"><strong aria-hidden="true">9.</strong> Memory model</a></li><li><ol class="section"><li><a href="memory-allocation-and-lifetime.html"><strong aria-hidden="true">9.1.</strong> Memory allocation and lifetime</a></li><li><a href="memory-ownership.html"><strong aria-hidden="true">9.2.</strong> Memory ownership</a></li><li><a href="variables.html"><strong aria-hidden="true">9.3.</strong> Variables</a></li></ol></li><li><a href="linkage.html" class="active"><strong aria-hidden="true">10.</strong> Linkage</a></li><li><a href="unsafety.html"><strong aria-hidden="true">11.</strong> Unsafety</a></li><li><ol class="section"><li><a href="unsafe-functions.html"><strong aria-hidden="true">11.1.</strong> Unsafe functions</a></li><li><a href="unsafe-blocks.html"><strong aria-hidden="true">11.2.</strong> Unsafe blocks</a></li><li><a href="behavior-considered-undefined.html"><strong aria-hidden="true">11.3.</strong> Behavior considered undefined</a></li><li><a href="behavior-not-considered-unsafe.html"><strong aria-hidden="true">11.4.</strong> Behavior not considered unsafe</a></li></ol></li><li><a href="influences.html">Appendix: Influences</a></li><li class="affix"><a href="undocumented.html">Appendix: As-yet-undocumented Features</a></li><li class="affix"><a href="glossary.html">Appendix: Glossary</a></li></ol> </nav> <div id="page-wrapper" class="page-wrapper"> <div class="page"> <header><p class="warning"> For now, this reference is a best-effort document. We strive for validity and completeness, but are not yet there. In the future, the docs and lang teams will work together to figure out how best to do this. Until then, this is a best-effort attempt. If you find something wrong or missing, file an <a href="https://github.com/rust-lang-nursery/reference/issues">issue</a> or send in a pull request. </p></header> <div id="menu-bar" class="menu-bar"> <div id="menu-bar-sticky-container"> <div class="left-buttons"> <button id="sidebar-toggle" class="icon-button" type="button" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar"> <i class="fa fa-bars"></i> </button> <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="submenu"> <li><button class="theme" id="light">Light <span class="default">(default)</span></button></li> <li><button class="theme" id="rust">Rust</button></li> <li><button class="theme" id="coal">Coal</button></li> <li><button class="theme" id="navy">Navy</button></li> <li><button class="theme" id="ayu">Ayu</button></li> </ul> </div> <h1 class="menu-title">The Rust Reference</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> </div> </div> </div> <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM --> <script type="text/javascript"> 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> <a class="header" href="linkage.html#linkage" id="linkage"><h1>Linkage</h1></a> <p>The Rust compiler supports various methods to link crates together both statically and dynamically. This section will explore the various methods to link Rust crates together, and more information about native libraries can be found in the <a href="../book/ffi.html">FFI section of the book</a>.</p> <p>In one session of compilation, the compiler can generate multiple artifacts through the usage of either command line flags or the <code>crate_type</code> attribute. If one or more command line flags are specified, all <code>crate_type</code> attributes will be ignored in favor of only building the artifacts specified by command line.</p> <ul> <li> <p><code>--crate-type=bin</code>, <code>#[crate_type = "bin"]</code> - A runnable executable will be produced. This requires that there is a <code>main</code> function in the crate which will be run when the program begins executing. This will link in all Rust and native dependencies, producing a distributable binary.</p> </li> <li> <p><code>--crate-type=lib</code>, <code>#[crate_type = "lib"]</code> - A Rust library will be produced. This is an ambiguous concept as to what exactly is produced because a library can manifest itself in several forms. The purpose of this generic <code>lib</code> option is to generate the "compiler recommended" style of library. The output library will always be usable by rustc, but the actual type of library may change from time-to-time. The remaining output types are all different flavors of libraries, and the <code>lib</code> type can be seen as an alias for one of them (but the actual one is compiler-defined).</p> </li> <li> <p><code>--crate-type=dylib</code>, <code>#[crate_type = "dylib"]</code> - A dynamic Rust library will be produced. This is different from the <code>lib</code> output type in that this forces dynamic library generation. The resulting dynamic library can be used as a dependency for other libraries and/or executables. This output type will create <code>*.so</code> files on linux, <code>*.dylib</code> files on osx, and <code>*.dll</code> files on windows.</p> </li> <li> <p><code>--crate-type=staticlib</code>, <code>#[crate_type = "staticlib"]</code> - A static system library will be produced. This is different from other library outputs in that the Rust compiler will never attempt to link to <code>staticlib</code> outputs. The purpose of this output type is to create a static library containing all of the local crate's code along with all upstream dependencies. The static library is actually a <code>*.a</code> archive on linux and osx and a <code>*.lib</code> file on windows. This format is recommended for use in situations such as linking Rust code into an existing non-Rust application because it will not have dynamic dependencies on other Rust code.</p> </li> <li> <p><code>--crate-type=cdylib</code>, <code>#[crate_type = "cdylib"]</code> - A dynamic system library will be produced. This is used when compiling Rust code as a dynamic library to be loaded from another language. This output type will create <code>*.so</code> files on Linux, <code>*.dylib</code> files on macOS, and <code>*.dll</code> files on Windows.</p> </li> <li> <p><code>--crate-type=rlib</code>, <code>#[crate_type = "rlib"]</code> - A "Rust library" file will be produced. This is used as an intermediate artifact and can be thought of as a "static Rust library". These <code>rlib</code> files, unlike <code>staticlib</code> files, are interpreted by the Rust compiler in future linkage. This essentially means that <code>rustc</code> will look for metadata in <code>rlib</code> files like it looks for metadata in dynamic libraries. This form of output is used to produce statically linked executables as well as <code>staticlib</code> outputs.</p> </li> <li> <p><code>--crate-type=proc-macro</code>, <code>#[crate_type = "proc-macro"]</code> - The output produced is not specified, but if a <code>-L</code> path is provided to it then the compiler will recognize the output artifacts as a macro and it can be loaded for a program. If a crate is compiled with the <code>proc-macro</code> crate type it will forbid exporting any items in the crate other than those functions tagged <code>#[proc_macro_derive]</code> and those functions must also be placed at the crate root. Finally, the compiler will automatically set the <code>cfg(proc_macro)</code> annotation whenever any crate type of a compilation is the <code>proc-macro</code> crate type.</p> </li> </ul> <p>Note that these outputs are stackable in the sense that if multiple are specified, then the compiler will produce each form of output at once without having to recompile. However, this only applies for outputs specified by the same method. If only <code>crate_type</code> attributes are specified, then they will all be built, but if one or more <code>--crate-type</code> command line flags are specified, then only those outputs will be built.</p> <p>With all these different kinds of outputs, if crate A depends on crate B, then the compiler could find B in various different forms throughout the system. The only forms looked for by the compiler, however, are the <code>rlib</code> format and the dynamic library format. With these two options for a dependent library, the compiler must at some point make a choice between these two formats. With this in mind, the compiler follows these rules when determining what format of dependencies will be used:</p> <ol> <li> <p>If a static library is being produced, all upstream dependencies are required to be available in <code>rlib</code> formats. This requirement stems from the reason that a dynamic library cannot be converted into a static format.</p> <p>Note that it is impossible to link in native dynamic dependencies to a static library, and in this case warnings will be printed about all unlinked native dynamic dependencies.</p> </li> <li> <p>If an <code>rlib</code> file is being produced, then there are no restrictions on what format the upstream dependencies are available in. It is simply required that all upstream dependencies be available for reading metadata from.</p> <p>The reason for this is that <code>rlib</code> files do not contain any of their upstream dependencies. It wouldn't be very efficient for all <code>rlib</code> files to contain a copy of <code>libstd.rlib</code>!</p> </li> <li> <p>If an executable is being produced and the <code>-C prefer-dynamic</code> flag is not specified, then dependencies are first attempted to be found in the <code>rlib</code> format. If some dependencies are not available in an rlib format, then dynamic linking is attempted (see below).</p> </li> <li> <p>If a dynamic library or an executable that is being dynamically linked is being produced, then the compiler will attempt to reconcile the available dependencies in either the rlib or dylib format to create a final product.</p> <p>A major goal of the compiler is to ensure that a library never appears more than once in any artifact. For example, if dynamic libraries B and C were each statically linked to library A, then a crate could not link to B and C together because there would be two copies of A. The compiler allows mixing the rlib and dylib formats, but this restriction must be satisfied.</p> <p>The compiler currently implements no method of hinting what format a library should be linked with. When dynamically linking, the compiler will attempt to maximize dynamic dependencies while still allowing some dependencies to be linked in via an rlib.</p> <p>For most situations, having all libraries available as a dylib is recommended if dynamically linking. For other situations, the compiler will emit a warning if it is unable to determine which formats to link each library with.</p> </li> </ol> <p>In general, <code>--crate-type=bin</code> or <code>--crate-type=lib</code> should be sufficient for all compilation needs, and the other options are just available if more fine-grained control is desired over the output format of a Rust crate.</p> <a class="header" href="linkage.html#static-and-dynamic-c-runtimes" id="static-and-dynamic-c-runtimes"><h2>Static and dynamic C runtimes</h2></a> <p>The standard library in general strives to support both statically linked and dynamically linked C runtimes for targets as appropriate. For example the <code>x86_64-pc-windows-msvc</code> and <code>x86_64-unknown-linux-musl</code> targets typically come with both runtimes and the user selects which one they'd like. All targets in the compiler have a default mode of linking to the C runtime. Typically targets are linked dynamically by default, but there are exceptions which are static by default such as:</p> <ul> <li><code>arm-unknown-linux-musleabi</code></li> <li><code>arm-unknown-linux-musleabihf</code></li> <li><code>armv7-unknown-linux-musleabihf</code></li> <li><code>i686-unknown-linux-musl</code></li> <li><code>x86_64-unknown-linux-musl</code></li> </ul> <p>The linkage of the C runtime is configured to respect the <code>crt-static</code> target feature. These target features are typically configured from the command line via flags to the compiler itself. For example to enable a static runtime you would execute:</p> <pre><code class="language-notrust">rustc -C target-feature=+crt-static foo.rs </code></pre> <p>whereas to link dynamically to the C runtime you would execute:</p> <pre><code class="language-notrust">rustc -C target-feature=-crt-static foo.rs </code></pre> <p>Targets which do not support switching between linkage of the C runtime will ignore this flag. It's recommended to inspect the resulting binary to ensure that it's linked as you would expect after the compiler succeeds.</p> <p>Crates may also learn about how the C runtime is being linked. Code on MSVC, for example, needs to be compiled differently (e.g. with <code>/MT</code> or <code>/MD</code>) depending on the runtime being linked. This is exported currently through the <code>target_feature</code> attribute (note this is a nightly feature):</p> <pre><code class="language-rust ignore">#[cfg(target_feature = "crt-static")] fn foo() { println!("the C runtime should be statically linked"); } #[cfg(not(target_feature = "crt-static"))] fn foo() { println!("the C runtime should be dynamically linked"); } </code></pre> <p>Also note that Cargo build scripts can learn about this feature through <a href="http://doc.crates.io/environment-variables.html#environment-variables-cargo-sets-for-build-scripts">environment variables</a>. In a build script you can detect the linkage via:</p> <pre><pre class="playpen"><code class="language-rust">use std::env; fn main() { let linkage = env::var("CARGO_CFG_TARGET_FEATURE").unwrap_or(String::new()); if linkage.contains("crt-static") { println!("the C runtime will be statically linked"); } else { println!("the C runtime will be dynamically linked"); } } </code></pre></pre> <p>To use this feature locally, you typically will use the <code>RUSTFLAGS</code> environment variable to specify flags to the compiler through Cargo. For example to compile a statically linked binary on MSVC you would execute:</p> <pre><code class="language-ignore notrust">RUSTFLAGS='-C target-feature=+crt-static' cargo build --target x86_64-pc-windows-msvc </code></pre> </main> <nav class="nav-wrapper" aria-label="Page navigation"> <!-- Mobile navigation buttons --> <a rel="prev" href="variables.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" href="unsafety.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 href="variables.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left"> <i class="fa fa-angle-left"></i> </a> <a href="unsafety.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> <!-- Local fallback for Font Awesome --> <script> if (getComputedStyle(document.querySelector(".fa")).fontFamily !== "FontAwesome") { var link = document.createElement('link'); link.rel = 'stylesheet'; link.type = 'text/css'; link.href = '_FontAwesome/css/font-awesome.css'; document.head.insertBefore(link, document.head.firstChild) } </script> <script src="highlight.js"></script> <script src="book.js"></script> <!-- Custom JS script --> </body> </html>