| <!DOCTYPE HTML> |
| <html lang="en" class="light sidebar-visible" dir="ltr"> |
| <head> |
| <!-- Book generated using mdBook --> |
| <meta charset="UTF-8"> |
| <title>How to build and run the compiler - 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/building/how-to-build-and-run.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="how-to-build-and-run-the-compiler"><a class="header" href="#how-to-build-and-run-the-compiler">How to build and run the compiler</a></h1> |
| <div class="warning"> |
| <p>For <code>profile = "library"</code> users, or users who use <code>download-rustc = true | "if-unchanged"</code>, please be advised that |
| the <code>./x test library/std</code> flow where <code>download-rustc</code> is active (i.e. no compiler changes) is currently broken. |
| This is tracked in <a href="https://github.com/rust-lang/rust/issues/142505">https://github.com/rust-lang/rust/issues/142505</a>. Only the <code>./x test</code> flow is affected in this |
| case, <code>./x {check,build} library/std</code> should still work.</p> |
| <p>In the short-term, you may need to disable <code>download-rustc</code> for <code>./x test library/std</code>. This can be done either by:</p> |
| <ol> |
| <li><code>./x test library/std --set rust.download-rustc=false</code></li> |
| <li>Or set <code>rust.download-rustc=false</code> in <code>bootstrap.toml</code>.</li> |
| </ol> |
| <p>Unfortunately that will require building the stage 1 compiler. The bootstrap team is working on this, but |
| implementing a maintainable fix is taking some time.</p> |
| </div> |
| <p>The compiler is built using a tool called <code>x.py</code>. You will need to |
| have Python installed to run it.</p> |
| <h2 id="quick-start"><a class="header" href="#quick-start">Quick Start</a></h2> |
| <p>For a less in-depth quick-start of getting the compiler running, see <a href="./quickstart.html">quickstart</a>.</p> |
| <h2 id="get-the-source-code"><a class="header" href="#get-the-source-code">Get the source code</a></h2> |
| <p>The main repository is <a href="https://github.com/rust-lang/rust"><code>rust-lang/rust</code></a>. This contains the compiler, |
| the standard library (including <code>core</code>, <code>alloc</code>, <code>test</code>, <code>proc_macro</code>, etc), |
| and a bunch of tools (e.g. <code>rustdoc</code>, the bootstrapping infrastructure, etc).</p> |
| <p>The very first step to work on <code>rustc</code> is to clone the repository:</p> |
| <pre><code class="language-bash">git clone https://github.com/rust-lang/rust.git |
| cd rust |
| </code></pre> |
| <h3 id="partial-clone-the-repository"><a class="header" href="#partial-clone-the-repository">Partial clone the repository</a></h3> |
| <p>Due to the size of the repository, cloning on a slower internet connection can take a long time, |
| and requires disk space to store the full history of every file and directory. |
| Instead, it is possible to tell git to perform a <em>partial clone</em>, which will only fully retrieve |
| the current file contents, but will automatically retrieve further file contents when you, e.g., |
| jump back in the history. |
| All git commands will continue to work as usual, at the price of requiring an internet connection |
| to visit not-yet-loaded points in history.</p> |
| <pre><code class="language-bash">git clone --filter='blob:none' https://github.com/rust-lang/rust.git |
| cd rust |
| </code></pre> |
| <blockquote> |
| <p><strong>NOTE</strong>: <a href="https://github.blog/open-source/git/get-up-to-speed-with-partial-clone-and-shallow-clone/">This link</a> |
| describes this type of checkout in more detail, and also compares it to other modes, such as |
| shallow cloning.</p> |
| </blockquote> |
| <h3 id="shallow-clone-the-repository"><a class="header" href="#shallow-clone-the-repository">Shallow clone the repository</a></h3> |
| <p>An older alternative to partial clones is to use shallow clone the repository instead. |
| To do so, you can use the <code>--depth N</code> option with the <code>git clone</code> command. |
| This instructs <code>git</code> to perform a "shallow clone", cloning the repository but truncating it to |
| the last <code>N</code> commits.</p> |
| <p>Passing <code>--depth 1</code> tells <code>git</code> to clone the repository but truncate the history to the latest |
| commit that is on the <code>master</code> branch, which is usually fine for browsing the source code or |
| building the compiler.</p> |
| <pre><code class="language-bash">git clone --depth 1 https://github.com/rust-lang/rust.git |
| cd rust |
| </code></pre> |
| <blockquote> |
| <p><strong>NOTE</strong>: A shallow clone limits which <code>git</code> commands can be run. |
| If you intend to work on and contribute to the compiler, it is |
| generally recommended to fully clone the repository <a href="#get-the-source-code">as shown above</a>, |
| or to perform a <a href="#partial-clone-the-repository">partial clone</a> instead.</p> |
| <p>For example, <code>git bisect</code> and <code>git blame</code> require access to the commit history, |
| so they don't work if the repository was cloned with <code>--depth 1</code>.</p> |
| </blockquote> |
| <h2 id="what-is-xpy"><a class="header" href="#what-is-xpy">What is <code>x.py</code>?</a></h2> |
| <p><code>x.py</code> is the build tool for the <code>rust</code> repository. It can build docs, run tests, and compile the |
| compiler and standard library.</p> |
| <p>This chapter focuses on the basics to be productive, but |
| if you want to learn more about <code>x.py</code>, <a href="./bootstrapping/intro.html">read this chapter</a>.</p> |
| <p>Also, using <code>x</code> rather than <code>x.py</code> is recommended as:</p> |
| <blockquote> |
| <p><code>./x</code> is the most likely to work on every system (on Unix it runs the shell script |
| that does python version detection, on Windows it will probably run the |
| powershell script - certainly less likely to break than <code>./x.py</code> which often just |
| opens the file in an editor).<sup class="footnote-reference" id="fr-1-1"><a href="#footnote-1">1</a></sup></p> |
| </blockquote> |
| <p>(You can find the platform related scripts around the <code>x.py</code>, like <code>x.ps1</code>)</p> |
| <p>Notice that this is not absolute. For instance, using Nushell in VSCode on Win10, |
| typing <code>x</code> or <code>./x</code> still opens <code>x.py</code> in an editor rather than invoking the program. :)</p> |
| <p>In the rest of this guide, we use <code>x</code> rather than <code>x.py</code> directly. The following |
| command:</p> |
| <pre><code class="language-bash">./x check |
| </code></pre> |
| <p>could be replaced by:</p> |
| <pre><code class="language-bash">./x.py check |
| </code></pre> |
| <h3 id="running-xpy"><a class="header" href="#running-xpy">Running <code>x.py</code></a></h3> |
| <p>The <code>x.py</code> command can be run directly on most Unix systems in the following format:</p> |
| <pre><code class="language-sh">./x <subcommand> [flags] |
| </code></pre> |
| <p>This is how the documentation and examples assume you are running <code>x.py</code>. |
| Some alternative ways are:</p> |
| <pre><code class="language-sh"># On a Unix shell if you don't have the necessary `python3` command |
| ./x <subcommand> [flags] |
| |
| # In Windows Powershell (if powershell is configured to run scripts) |
| ./x <subcommand> [flags] |
| ./x.ps1 <subcommand> [flags] |
| |
| # On the Windows Command Prompt (if .py files are configured to run Python) |
| x.py <subcommand> [flags] |
| |
| # You can also run Python yourself, e.g.: |
| python x.py <subcommand> [flags] |
| </code></pre> |
| <p>On Windows, the Powershell commands may give you an error that looks like this:</p> |
| <pre><code>PS C:\Users\vboxuser\rust> ./x |
| ./x : File C:\Users\vboxuser\rust\x.ps1 cannot be loaded because running scripts is disabled on this system. For more |
| information, see about_Execution_Policies at https://go.microsoft.com/fwlink/?LinkID=135170. |
| At line:1 char:1 |
| + ./x |
| + ~~~ |
| + CategoryInfo : SecurityError: (:) [], PSSecurityException |
| + FullyQualifiedErrorId : UnauthorizedAccess |
| </code></pre> |
| <p>You can avoid this error by allowing powershell to run local scripts:</p> |
| <pre><code>Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser |
| </code></pre> |
| <h4 id="running-xpy-slightly-more-conveniently"><a class="header" href="#running-xpy-slightly-more-conveniently">Running <code>x.py</code> slightly more conveniently</a></h4> |
| <p>There is a binary that wraps <code>x.py</code> called <code>x</code> in <code>src/tools/x</code>. All it does is |
| run <code>x.py</code>, but it can be installed system-wide and run from any subdirectory |
| of a checkout. It also looks up the appropriate version of <code>python</code> to use.</p> |
| <p>You can install it with <code>cargo install --path src/tools/x</code>.</p> |
| <p>To clarify that this is another global installed binary util, which is |
| similar to the one declared in section <a href="#what-is-xpy">What is <code>x.py</code></a>, but |
| it works as an independent process to execute the <code>x.py</code> rather than calling the |
| shell to run the platform related scripts.</p> |
| <h2 id="create-a-bootstraptoml"><a class="header" href="#create-a-bootstraptoml">Create a <code>bootstrap.toml</code></a></h2> |
| <p>To start, run <code>./x setup</code> and select the <code>compiler</code> defaults. This will do some initialization |
| and create a <code>bootstrap.toml</code> for you with reasonable defaults. If you use a different default (which |
| you'll likely want to do if you want to contribute to an area of rust other than the compiler, such |
| as rustdoc), make sure to read information about that default (located in <code>src/bootstrap/defaults</code>) |
| as the build process may be different for other defaults.</p> |
| <p>Alternatively, you can write <code>bootstrap.toml</code> by hand. See <code>bootstrap.example.toml</code> for all the available |
| settings and explanations of them. See <code>src/bootstrap/defaults</code> for common settings to change.</p> |
| <p>If you have already built <code>rustc</code> and you change settings related to LLVM, then you may have to |
| execute <code>rm -rf build</code> for subsequent configuration changes to take effect. Note that <code>./x clean</code> will not cause a rebuild of LLVM.</p> |
| <h2 id="common-x-commands"><a class="header" href="#common-x-commands">Common <code>x</code> commands</a></h2> |
| <p>Here are the basic invocations of the <code>x</code> commands most commonly used when |
| working on <code>rustc</code>, <code>std</code>, <code>rustdoc</code>, and other tools.</p> |
| <div class="table-wrapper"><table><thead><tr><th>Command</th><th>When to use it</th></tr></thead><tbody> |
| <tr><td><code>./x check</code></td><td>Quick check to see if most things compile; <a href="suggested.html#configuring-rust-analyzer-for-rustc">rust-analyzer can run this automatically for you</a></td></tr> |
| <tr><td><code>./x build</code></td><td>Builds <code>rustc</code>, <code>std</code>, and <code>rustdoc</code></td></tr> |
| <tr><td><code>./x test</code></td><td>Runs all tests</td></tr> |
| <tr><td><code>./x fmt</code></td><td>Formats all code</td></tr> |
| </tbody></table> |
| </div> |
| <p>As written, these commands are reasonable starting points. However, there are |
| additional options and arguments for each of them that are worth learning for |
| serious development work. In particular, <code>./x build</code> and <code>./x test</code> |
| provide many ways to compile or test a subset of the code, which can save a lot |
| of time.</p> |
| <p>Also, note that <code>x</code> supports all kinds of path suffixes for <code>compiler</code>, <code>library</code>, |
| and <code>src/tools</code> directories. So, you can simply run <code>x test tidy</code> instead of |
| <code>x test src/tools/tidy</code>. Or, <code>x build std</code> instead of <code>x build library/std</code>.</p> |
| <p>See the chapters on |
| <a href="../tests/running.html">testing</a> and <a href="../rustdoc.html">rustdoc</a> for more details.</p> |
| <h3 id="building-the-compiler"><a class="header" href="#building-the-compiler">Building the compiler</a></h3> |
| <p>Note that building will require a relatively large amount of storage space. |
| You may want to have upwards of 10 or 15 gigabytes available to build the compiler.</p> |
| <p>Once you've created a <code>bootstrap.toml</code>, you are now ready to run |
| <code>x</code>. There are a lot of options here, but let's start with what is |
| probably the best "go to" command for building a local compiler:</p> |
| <pre><code class="language-bash">./x build library |
| </code></pre> |
| <p>This may <em>look</em> like it only builds the standard library, but that is not the case. |
| What this command does is the following:</p> |
| <ul> |
| <li>Build <code>rustc</code> using the stage0 compiler |
| <ul> |
| <li>This produces the stage1 compiler</li> |
| </ul> |
| </li> |
| <li>Build <code>std</code> using the stage1 compiler</li> |
| </ul> |
| <p>This final product (stage1 compiler + libs built using that compiler) |
| is what you need to build other Rust programs (unless you use <code>#![no_std]</code> or |
| <code>#![no_core]</code>).</p> |
| <p>You will probably find that building the stage1 <code>std</code> is a bottleneck for you, |
| but fear not, there is a (hacky) workaround... |
| see <a href="./suggested.html#faster-builds-with---keep-stage">the section on avoiding rebuilds for std</a>.</p> |
| <p>Sometimes you don't need a full build. When doing some kind of |
| "type-based refactoring", like renaming a method, or changing the |
| signature of some function, you can use <code>./x check</code> instead for a much faster build.</p> |
| <p>Note that this whole command just gives you a subset of the full <code>rustc</code> |
| build. The <strong>full</strong> <code>rustc</code> build (what you get with <code>./x build --stage 2 compiler/rustc</code>) has quite a few more steps:</p> |
| <ul> |
| <li>Build <code>rustc</code> with the stage1 compiler. |
| <ul> |
| <li>The resulting compiler here is called the "stage2" compiler, which uses stage1 std from the previous command.</li> |
| </ul> |
| </li> |
| <li>Build <code>librustdoc</code> and a bunch of other things with the stage2 compiler.</li> |
| </ul> |
| <p>You almost never need to do this.</p> |
| <h3 id="build-specific-components"><a class="header" href="#build-specific-components">Build specific components</a></h3> |
| <p>If you are working on the standard library, you probably don't need to build |
| every other default component. Instead, you can build a specific component by |
| providing its name, like this:</p> |
| <pre><code class="language-bash">./x build --stage 1 library |
| </code></pre> |
| <p>If you choose the <code>library</code> profile when running <code>x setup</code>, you can omit <code>--stage 1</code> (it's the |
| default).</p> |
| <h2 id="creating-a-rustup-toolchain"><a class="header" href="#creating-a-rustup-toolchain">Creating a rustup toolchain</a></h2> |
| <p>Once you have successfully built <code>rustc</code>, you will have created a bunch |
| of files in your <code>build</code> directory. In order to actually run the |
| resulting <code>rustc</code>, we recommend creating rustup toolchains. The first |
| one will run the stage1 compiler (which we built above). The second |
| will execute the stage2 compiler (which we did not build, but which |
| you will likely need to build at some point; for example, if you want |
| to run the entire test suite).</p> |
| <pre><code class="language-bash">rustup toolchain link stage1 build/host/stage1 |
| rustup toolchain link stage2 build/host/stage2 |
| </code></pre> |
| <p>Now you can run the <code>rustc</code> you built with. If you run with <code>-vV</code>, you |
| should see a version number ending in <code>-dev</code>, indicating a build from |
| your local environment:</p> |
| <pre><code class="language-bash">$ rustc +stage1 -vV |
| rustc 1.48.0-dev |
| binary: rustc |
| commit-hash: unknown |
| commit-date: unknown |
| host: x86_64-unknown-linux-gnu |
| release: 1.48.0-dev |
| LLVM version: 11.0 |
| </code></pre> |
| <p>The rustup toolchain points to the specified toolchain compiled in your <code>build</code> directory, |
| so the rustup toolchain will be updated whenever <code>x build</code> or <code>x test</code> are run for |
| that toolchain/stage.</p> |
| <p><strong>Note:</strong> the toolchain we've built does not include <code>cargo</code>. In this case, <code>rustup</code> will |
| fall back to using <code>cargo</code> from the installed <code>nightly</code>, <code>beta</code>, or <code>stable</code> toolchain |
| (in that order). If you need to use unstable <code>cargo</code> flags, be sure to run |
| <code>rustup install nightly</code> if you haven't already. See the |
| <a href="https://rust-lang.github.io/rustup/concepts/toolchains.html#custom-toolchains">rustup documentation on custom toolchains</a>.</p> |
| <p><strong>Note:</strong> rust-analyzer and IntelliJ Rust plugin use a component called |
| <code>rust-analyzer-proc-macro-srv</code> to work with proc macros. If you intend to use a |
| custom toolchain for a project (e.g. via <code>rustup override set stage1</code>) you may |
| want to build this component:</p> |
| <pre><code class="language-bash">./x build proc-macro-srv-cli |
| </code></pre> |
| <h2 id="building-targets-for-cross-compilation"><a class="header" href="#building-targets-for-cross-compilation">Building targets for cross-compilation</a></h2> |
| <p>To produce a compiler that can cross-compile for other targets, |
| pass any number of <code>target</code> flags to <code>x build</code>. |
| For example, if your host platform is <code>x86_64-unknown-linux-gnu</code> |
| and your cross-compilation target is <code>wasm32-wasip1</code>, you can build with:</p> |
| <pre><code class="language-bash">./x build --target x86_64-unknown-linux-gnu,wasm32-wasip1 |
| </code></pre> |
| <p>Note that if you want the resulting compiler to be able to build crates that |
| involve proc macros or build scripts, you must be sure to explicitly build target support for the |
| host platform (in this case, <code>x86_64-unknown-linux-gnu</code>).</p> |
| <p>If you want to always build for other targets without needing to pass flags to <code>x build</code>, |
| you can configure this in the <code>[build]</code> section of your <code>bootstrap.toml</code> like so:</p> |
| <pre><code class="language-toml">[build] |
| target = ["x86_64-unknown-linux-gnu", "wasm32-wasip1"] |
| </code></pre> |
| <p>Note that building for some targets requires having external dependencies installed |
| (e.g. building musl targets requires a local copy of musl). |
| Any target-specific configuration (e.g. the path to a local copy of musl) |
| will need to be provided by your <code>bootstrap.toml</code>. |
| Please see <code>bootstrap.example.toml</code> for information on target-specific configuration keys.</p> |
| <p>For examples of the complete configuration necessary to build a target, please visit |
| <a href="https://doc.rust-lang.org/rustc/platform-support.html">the rustc book</a>, |
| select any target under the "Platform Support" heading on the left, |
| and see the section related to building a compiler for that target. |
| For targets without a corresponding page in the rustc book, |
| it may be useful to <a href="../tests/docker.html">inspect the Dockerfiles</a> |
| that the Rust infrastructure itself uses to set up and configure cross-compilation.</p> |
| <p>If you have followed the directions from the prior section on creating a rustup toolchain, |
| then once you have built your compiler you will be able to use it to cross-compile like so:</p> |
| <pre><code class="language-bash">cargo +stage1 build --target wasm32-wasip1 |
| </code></pre> |
| <h2 id="other-x-commands"><a class="header" href="#other-x-commands">Other <code>x</code> commands</a></h2> |
| <p>Here are a few other useful <code>x</code> commands. We'll cover some of them in detail |
| in other sections:</p> |
| <ul> |
| <li>Building things: |
| <ul> |
| <li><code>./x build</code> – builds everything using the stage 1 compiler, |
| not just up to <code>std</code></li> |
| <li><code>./x build --stage 2</code> – builds everything with the stage 2 compiler including |
| <code>rustdoc</code></li> |
| </ul> |
| </li> |
| <li>Running tests (see the <a href="../tests/running.html">section on running tests</a> for |
| more details): |
| <ul> |
| <li><code>./x test library/std</code> – runs the unit tests and integration tests from <code>std</code></li> |
| <li><code>./x test tests/ui</code> – runs the <code>ui</code> test suite</li> |
| <li><code>./x test tests/ui/const-generics</code> - runs all the tests in |
| the <code>const-generics/</code> subdirectory of the <code>ui</code> test suite</li> |
| <li><code>./x test tests/ui/const-generics/const-types.rs</code> - runs |
| the single test <code>const-types.rs</code> from the <code>ui</code> test suite</li> |
| </ul> |
| </li> |
| </ul> |
| <h3 id="cleaning-out-build-directories"><a class="header" href="#cleaning-out-build-directories">Cleaning out build directories</a></h3> |
| <p>Sometimes you need to start fresh, but this is normally not the case. |
| If you need to run this then bootstrap is most likely not acting right and |
| you should file a bug as to what is going wrong. If you do need to clean |
| everything up then you only need to run one command!</p> |
| <pre><code class="language-bash">./x clean |
| </code></pre> |
| <p><code>rm -rf build</code> works too, but then you have to rebuild LLVM, which can take |
| a long time even on fast computers.</p> |
| <h2 id="remarks-on-disk-space"><a class="header" href="#remarks-on-disk-space">Remarks on disk space</a></h2> |
| <p>Building the compiler (especially if beyond stage 1) can require significant amounts of free disk |
| space, possibly around 100GB. This is compounded if you have a separate build directory for |
| rust-analyzer (e.g. <code>build-rust-analyzer</code>). This is easy to hit with dev-desktops which have a <a href="https://github.com/rust-lang/simpleinfra/blob/8a59e4faeb75a09b072671c74a7cb70160ebef50/ansible/roles/dev-desktop/defaults/main.yml#L7">set |
| disk |
| quota</a> |
| for each user, but this also applies to local development as well. Occasionally, you may need to:</p> |
| <ul> |
| <li>Remove <code>build/</code> directory.</li> |
| <li>Remove <code>build-rust-analyzer/</code> directory (if you have a separate rust-analyzer build directory).</li> |
| <li>Uninstall unnecessary toolchains if you use <code>cargo-bisect-rustc</code>. You can check which toolchains |
| are installed with <code>rustup toolchain list</code>.</li> |
| </ul> |
| <hr> |
| <ol class="footnote-definition"><li id="footnote-1"> |
| <p>issue<a href="https://github.com/rust-lang/rustc-dev-guide/issues/1707">#1707</a> <a href="#fr-1-1">↩</a></p> |
| </li> |
| </ol> |
| </main> |
| |
| <nav class="nav-wrapper" aria-label="Page navigation"> |
| <!-- Mobile navigation buttons --> |
| <a rel="prev" href="../about-this-guide.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="../building/quickstart.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="../about-this-guide.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="../building/quickstart.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> |
