| <!DOCTYPE HTML> |
| <html lang="en" class="light sidebar-visible" dir="ltr"> |
| <head> |
| <!-- Book generated using mdBook --> |
| <meta charset="UTF-8"> |
| <title>Introduction - 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> |
| <h1 id="rules-rust"><a class="header" href="#rules-rust">Rules Rust</a></h1> |
| <p>This repository provides rules for building <a href="http://www.rust-lang.org/">Rust</a> projects with <a href="https://bazel.build/">Bazel</a>.</p> |
| <!-- TODO: Render generated docs on the github pages site again, https://bazelbuild.github.io/rules_rust/ --> |
| <p><a name="setup"></a></p> |
| <h2 id="setup"><a class="header" href="#setup">Setup</a></h2> |
| <p>The rules are released, and releases can be found on <a href="https://github.com/bazelbuild/rules_rust/releases">the GitHub Releases page</a>. We recommend using the latest release from that page.</p> |
| <h3 id="bzlmod"><a class="header" href="#bzlmod">Bzlmod</a></h3> |
| <p>Note that rules_rust bzlmod support is still a work in progress. Most features should work, but bugs are more likely. This is not a desired end-state - please report (or better yet, help fix!) bugs you run into.</p> |
| <p>To use <code>rules_rust</code> in a project using bzlmod, add the following to your <code>MODULE.bazel</code> file:</p> |
| <pre><code class="language-python">bazel_dep(name = "rules_rust", version = "0.65.0") |
| </code></pre> |
| <p>Don't forget to substitute in your desired release's version number.</p> |
| <h3 id="workspace"><a class="header" href="#workspace">WORKSPACE</a></h3> |
| <p>To use <code>rules_rust</code> in a project using a WORKSPACE file, add the following to your <code>WORKSPACE</code> file to add the external repositories for the Rust toolchain:</p> |
| <pre><code class="language-python">load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive") |
| |
| # To find additional information on this release or newer ones visit: |
| # https://github.com/bazelbuild/rules_rust/releases |
| http_archive( |
| name = "rules_rust", |
| integrity = "sha256-Weev1uz2QztBlDA88JX6A1N72SucD1V8lBsaliM0TTg=", |
| urls = ["https://github.com/bazelbuild/rules_rust/releases/download/0.48.0/rules_rust-v0.48.0.tar.gz"], |
| ) |
| |
| load("@rules_rust//rust:repositories.bzl", "rules_rust_dependencies", "rust_register_toolchains") |
| |
| rules_rust_dependencies() |
| |
| rust_register_toolchains() |
| </code></pre> |
| <p>Don't forget to substitute in your desired release's version number and integrity hash.</p> |
| <h2 id="specifying-rust-version"><a class="header" href="#specifying-rust-version">Specifying Rust version</a></h2> |
| <h3 id="bzlmod-1"><a class="header" href="#bzlmod-1">Bzlmod</a></h3> |
| <p>To use a particular version of the Rust compiler, pass that version to the <code>toolchain</code> method of the <code>rust</code> extension, like this:</p> |
| <pre><code class="language-python">rust = use_extension("@rules_rust//rust:extensions.bzl", "rust") |
| rust.toolchain( |
| edition = "2024", |
| versions = [ "1.85.0" ], |
| ) |
| </code></pre> |
| <p>As well as an exact version, <code>versions</code> can accept <code>nightly/{iso_date}</code> and <code>beta/{iso_date}</code> strings for toolchains from different release channels, as in</p> |
| <pre><code class="language-python">rust.toolchain( |
| edition = "2021", |
| versions = [ "nightly/1.85.0" ], |
| ) |
| </code></pre> |
| <p>By default, a <code>stable</code> and <code>nightly</code> toolchain will be registered if no <code>toolchain</code> method is called (and thus no specific versions are registered). However, if only 1 version is passed and it is from the <code>nightly</code> or <code>beta</code> release channels (i.e. <strong>not</strong> <code>stable</code>), then the following build setting flag must be present, either on the command line or set in the project's <code>.bazelrc</code> file:</p> |
| <pre><code class="language-text">build --@rules_rust//rust/toolchain/channel=nightly |
| </code></pre> |
| <p>Failure to do so will result in rules attempting to match a <code>stable</code> toolchain when one was not registered, thus raising an error.</p> |
| <h3 id="workspace-1"><a class="header" href="#workspace-1">WORKSPACE</a></h3> |
| <p>To build with a particular version of the Rust compiler when using a WORKSPACE file, pass that version to <code>rust_register_toolchains</code>:</p> |
| <pre><code class="language-python">rust_register_toolchains( |
| edition = "2021", |
| versions = [ |
| "1.79.0" |
| ], |
| ) |
| </code></pre> |
| <p>Like in the Bzlmod approach, as well as an exact version, <code>versions</code> can accept <code>nightly/{iso_date}</code> and <code>beta/{iso_date}</code> strings for toolchains from different release channels.</p> |
| <pre><code class="language-python">rust_register_toolchains( |
| edition = "2021", |
| versions = [ |
| "nightly/2024-06-13", |
| ], |
| ) |
| </code></pre> |
| <p>Here too a <code>stable</code> and <code>nightly</code> toolchain will be registered by default if no versions are passed to <code>rust_register_toolchains</code>. However, |
| if only 1 version is passed and it is from the <code>nightly</code> or <code>beta</code> release channels (i.e. <strong>not</strong> <code>stable</code>), then the following build setting flag must |
| also be set either in the command line or in the project's <code>.bazelrc</code> file.</p> |
| <pre><code class="language-text">build --@rules_rust//rust/toolchain/channel=nightly |
| </code></pre> |
| <p>Failure to do so will result in rules attempting to match a <code>stable</code> toolchain when one was not registered, thus raising an error.</p> |
| <h2 id="supported-bazel-versions"><a class="header" href="#supported-bazel-versions">Supported bazel versions</a></h2> |
| <p>The oldest version of Bazel the <code>main</code> branch is tested against is <code>7.4.1</code>. Previous versions may still be functional in certain environments, but this is the minimum version we strive to fully support.</p> |
| <p>We test these rules against the latest rolling releases of Bazel, and aim for compatibility with them, but prioritise stable releases over rolling releases where necessary.</p> |
| <h3 id="workspace-support"><a class="header" href="#workspace-support">WORKSPACE support</a></h3> |
| <p>WORKSPACE support is officially tested with Bazel 7 for as long as that is the min supported version. While it may work with later versions, compatibility with those versions is not guaranteed or actively verified.</p> |
| <h2 id="supported-platforms"><a class="header" href="#supported-platforms">Supported platforms</a></h2> |
| <p>We aim to support Linux and macOS.</p> |
| <p>We do not have sufficient maintainer expertise to support Windows. Most things probably work, but we have had to disable many tests in CI because we lack the expertise to fix them. We welcome contributions to help improve its support.</p> |
| |
| </main> |
| |
| <nav class="nav-wrapper" aria-label="Page navigation"> |
| <!-- Mobile navigation buttons --> |
| |
| <a rel="next prefetch" href="rules.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="next prefetch" href="rules.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> |
