blob: 3a58e5422561dc1568de80ee5e621675f0d6631c [file]
<!DOCTYPE HTML>
<html lang="en" class="light sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>rust_dylib_library - rules_rust</title>
<!-- Custom HTML head -->
<meta name="description" content="">
<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" href="highlight.css">
<link rel="stylesheet" href="tomorrow-night.css">
<link rel="stylesheet" href="ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root to javascript -->
<script>
var path_to_root = "";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
</script>
<!-- Start loading toc.js asap -->
<script src="toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
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>
var 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>
var sidebar = null;
var 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 = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</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="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. (Shortkey: s)" 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">rules_rust</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/bazelbuild/rules_rust" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</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>
<!-- Generated with Stardoc: http://skydoc.bazel.build -->
<p>rust_dylib_library</p>
<p><a id="rust_dylib_library"></a></p>
<h2 id="rust_dylib_library"><a class="header" href="#rust_dylib_library">rust_dylib_library</a></h2>
<pre>
load("@rules_rust//rust:rust_dylib_library.bzl", "rust_dylib_library")
rust_dylib_library(<a href="#rust_dylib_library-name">name</a>, <a href="#rust_dylib_library-deps">deps</a>, <a href="#rust_dylib_library-srcs">srcs</a>, <a href="#rust_dylib_library-data">data</a>, <a href="#rust_dylib_library-aliases">aliases</a>, <a href="#rust_dylib_library-allocator_libraries">allocator_libraries</a>, <a href="#rust_dylib_library-alwayslink">alwayslink</a>, <a href="#rust_dylib_library-compile_data">compile_data</a>,
<a href="#rust_dylib_library-crate_features">crate_features</a>, <a href="#rust_dylib_library-crate_name">crate_name</a>, <a href="#rust_dylib_library-crate_root">crate_root</a>, <a href="#rust_dylib_library-disable_pipelining">disable_pipelining</a>, <a href="#rust_dylib_library-edition">edition</a>, <a href="#rust_dylib_library-link_deps">link_deps</a>,
<a href="#rust_dylib_library-link_std_dylib">link_std_dylib</a>, <a href="#rust_dylib_library-lint_config">lint_config</a>, <a href="#rust_dylib_library-proc_macro_deps">proc_macro_deps</a>, <a href="#rust_dylib_library-require_explicit_unstable_features">require_explicit_unstable_features</a>,
<a href="#rust_dylib_library-root_path">root_path</a>, <a href="#rust_dylib_library-rustc_env">rustc_env</a>, <a href="#rust_dylib_library-rustc_env_files">rustc_env_files</a>, <a href="#rust_dylib_library-rustc_flags">rustc_flags</a>, <a href="#rust_dylib_library-stamp">stamp</a>,
<a href="#rust_dylib_library-unstable_rust_features_config">unstable_rust_features_config</a>, <a href="#rust_dylib_library-version">version</a>, <a href="#rust_dylib_library-zself_profile_events">zself_profile_events</a>)
</pre>
<p>Builds a shared library using the unstable Rust ABI.</p>
<p>This library can be depended on by other Rust targets via --extern,
making it suitable for splitting a Rust project into separately compiled
dynamic libraries. Note that the Rust ABI is not stable across compiler
versions.</p>
<p>This rule provides CcInfo, so it can be used everywhere Bazel expects <code>rules_cc</code>.</p>
<p><strong>Note</strong>: When dynamic libraries are listed as dependencies for other Rust
binaries they can induce errors from multiply defined symbols, causing
linker errors in rustc. Some libraries in the dependency graph may need to
be converted to dynamic libraries, and/or have the standard library
dynamically linked (<code>link_std_dylib</code>) to avoid this. These rules do not
attempt to resolve these linking issues automatically.</p>
<p><strong>ATTRIBUTES</strong></p>
<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Name</th><th style="text-align: left">Description</th><th style="text-align: left">Type</th><th style="text-align: left">Mandatory</th><th style="text-align: left">Default</th></tr></thead><tbody>
<tr><td style="text-align: left"><a id="rust_dylib_library-name"></a>name</td><td style="text-align: left">A unique name for this target.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels#target-names">Name</a></td><td style="text-align: left">required</td><td style="text-align: left"></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-deps"></a>deps</td><td style="text-align: left">List of other Rust libraries to be linked to this library target.<br><br>These must be targets that provide <code>CrateInfo</code>, such as <code>rust_library</code>.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-srcs"></a>srcs</td><td style="text-align: left">List of Rust <code>.rs</code> source files used to build the library.<br><br>If <code>srcs</code> contains more than one file, then there must be a file either named <code>lib.rs</code>. Otherwise, <code>crate_root</code> must be set to the source file that is the root of the crate to be passed to rustc to build this crate.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-data"></a>data</td><td style="text-align: left">List of files used by this rule at compile time and runtime.<br><br>If including data at compile time with include_str!() and similar, prefer <code>compile_data</code> over <code>data</code>, to prevent the data also being included in the runfiles.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-aliases"></a>aliases</td><td style="text-align: left">Remap crates to a new name or moniker for linkage to this target<br><br>These are other <code>rust_library</code> targets and will be presented as the new name given.</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: Label -&gt; String</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>{}</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-allocator_libraries"></a>allocator_libraries</td><td style="text-align: left">-</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>"@rules_rust//ffi/rs:default_allocator_libraries"</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-alwayslink"></a>alwayslink</td><td style="text-align: left">If 1, any binary that depends (directly or indirectly) on this library will link in all the object files even if some contain no symbols referenced by the binary.<br><br>This attribute is used by the C++ Starlark API when passing CcInfo providers.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>False</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-compile_data"></a>compile_data</td><td style="text-align: left">List of files used by this rule at compile time.<br><br>This attribute can be used to specify any data files that are embedded into the library, such as via the <a href="https://doc.rust-lang.org/std/macro.include_str!.html"><code>include_str!</code></a> macro.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-crate_features"></a>crate_features</td><td style="text-align: left">List of features to enable for this crate.<br><br>Features are defined in the code using the <code>#[cfg(feature = "foo")]</code> configuration option. The features listed here will be passed to <code>rustc</code> with <code>--cfg feature="${feature_name}"</code> flags.</td><td style="text-align: left">List of strings</td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-crate_name"></a>crate_name</td><td style="text-align: left">Crate name to use for this target.<br><br>This must be a valid Rust identifier, i.e. it may contain only alphanumeric characters and underscores. Defaults to the target name, with any hyphens replaced by underscores.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-crate_root"></a>crate_root</td><td style="text-align: left">The file that will be passed to <code>rustc</code> to be used for building this crate.<br><br>If <code>crate_root</code> is not set, then this rule will look for a <code>lib.rs</code> file (or <code>main.rs</code> for rust_binary) or the single file in <code>srcs</code> if <code>srcs</code> contains only one file.<br><br>If the <code>srcs</code> contains only one file and that file is a directory, use <code>root_path</code> to specify the path to the crate root .rs file under that directory.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-disable_pipelining"></a>disable_pipelining</td><td style="text-align: left">Disables pipelining for this rule if it is globally enabled. This will cause this rule to not produce a <code>.rmeta</code> file and all the dependent crates will instead use the <code>.rlib</code> file.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>False</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-edition"></a>edition</td><td style="text-align: left">The rust edition to use for this crate. Defaults to the edition specified in the rust_toolchain.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-link_deps"></a>link_deps</td><td style="text-align: left">List of other native libraries to be linked to this library target.<br><br>These are typically <code>cc_library</code> targets.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-link_std_dylib"></a>link_std_dylib</td><td style="text-align: left">Flag to dynamically link the standard library as a Rust dylib .so object when building this library.<br><br>Default is true. This is typically required for Rust ABI dylibs so that the stdlib is shared with the binary that loads them, avoiding duplicate symbols.</td><td style="text-align: left">Boolean</td><td style="text-align: left">optional</td><td style="text-align: left"><code>True</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-lint_config"></a>lint_config</td><td style="text-align: left">Set of lints to apply when building this crate.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-proc_macro_deps"></a>proc_macro_deps</td><td style="text-align: left">List of <code>rust_proc_macro</code> targets used to help build this library target.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-require_explicit_unstable_features"></a>require_explicit_unstable_features</td><td style="text-align: left">Whether to require all unstable features to be explicitly opted in to using <code>-Zallow-features=...</code>. Possible values: [-1, 0, 1]. -1 means delegate to the toolchain.require_explicit_unstable_features boolean build setting; 0 means False; 1 means True.</td><td style="text-align: left">Integer</td><td style="text-align: left">optional</td><td style="text-align: left"><code>-1</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-root_path"></a>root_path</td><td style="text-align: left">If the crate root (single member of the <code>srcs</code> list) is a directory, this is the path to the crate root <code>.rs</code> file under that directory.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>""</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-rustc_env"></a>rustc_env</td><td style="text-align: left">Dictionary of additional <code>"key": "value"</code> environment variables to set for rustc.<br><br>rust_test()/rust_binary() rules can use $(rootpath //package:target) to pass in the location of a generated file or external tool. Cargo build scripts that wish to expand locations should use cargo_build_script()'s build_script_env argument instead, as build scripts are run in a different environment - see cargo_build_script()'s documentation for more.</td><td style="text-align: left"><a href="https://bazel.build/rules/lib/dict">Dictionary: String -&gt; String</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>{}</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-rustc_env_files"></a>rustc_env_files</td><td style="text-align: left">Files containing additional environment variables to set for rustc.<br><br>These files should contain a single variable per line, of format <code>NAME=value</code>, and newlines may be included in a value by ending a line with a trailing back-slash (<code>\\</code>).<br><br>The order that these files will be processed is unspecified, so multiple definitions of a particular variable are discouraged.<br><br>Note that the variables here are subject to <a href="https://docs.bazel.build/versions/main/user-manual.html#workspace_status">workspace status</a> stamping should the <code>stamp</code> attribute be enabled. Stamp variables should be wrapped in brackets in order to be resolved. E.g. <code>NAME={WORKSPACE_STATUS_VARIABLE}</code>.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">List of labels</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-rustc_flags"></a>rustc_flags</td><td style="text-align: left">List of compiler flags passed to <code>rustc</code>.<br><br>These strings are subject to Make variable expansion for predefined source/output path variables like <code>$location</code>, <code>$execpath</code>, and <code>$rootpath</code>. This expansion is useful if you wish to pass a generated file of arguments to rustc: <code>@$(location //package:target)</code>.</td><td style="text-align: left">List of strings</td><td style="text-align: left">optional</td><td style="text-align: left"><code>[]</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-stamp"></a>stamp</td><td style="text-align: left">Whether to encode build information into the <code>Rustc</code> action. Possible values:<br><br>- <code>stamp = 1</code>: Always stamp the build information into the <code>Rustc</code> action, even in <a href="https://docs.bazel.build/versions/main/user-manual.html#flag--stamp">--nostamp</a> builds. This setting should be avoided, since it potentially kills remote caching for the target and any downstream actions that depend on it.<br><br>- <code>stamp = 0</code>: Always replace build information by constant values. This gives good build result caching.<br><br>- <code>stamp = -1</code>: Embedding of build information is controlled by the <a href="https://docs.bazel.build/versions/main/user-manual.html#flag--stamp">--[no]stamp</a> flag.<br><br>Stamped targets are not rebuilt unless their dependencies change.<br><br>For example if a <code>rust_library</code> is stamped, and a <code>rust_binary</code> depends on that library, the stamped library won't be rebuilt when we change sources of the <code>rust_binary</code>. This is different from how <a href="https://docs.bazel.build/versions/main/be/c-cpp.html#cc_library.linkstamp"><code>cc_library.linkstamps</code></a> behaves.</td><td style="text-align: left">Integer</td><td style="text-align: left">optional</td><td style="text-align: left"><code>0</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-unstable_rust_features_config"></a>unstable_rust_features_config</td><td style="text-align: left">Controls which unstable features are allowed to be used by this target. Setting this to anything other than None requires a nightly toolchain.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-version"></a>version</td><td style="text-align: left">A version to inject in the cargo environment variable.</td><td style="text-align: left">String</td><td style="text-align: left">optional</td><td style="text-align: left"><code>"0.0.0"</code></td></tr>
<tr><td style="text-align: left"><a id="rust_dylib_library-zself_profile_events"></a>zself_profile_events</td><td style="text-align: left">Passes -Zself-profile and -Zself-profile-events flag to rustc, requires a nightly toolchain.</td><td style="text-align: left"><a href="https://bazel.build/concepts/labels">Label</a></td><td style="text-align: left">optional</td><td style="text-align: left"><code>None</code></td></tr>
</tbody></table>
</div>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="rust_cdylib_library.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="rust_proc_macro.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="rust_cdylib_library.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="rust_proc_macro.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 -->
</div>
</body>
</html>