556 lines
32 KiB
HTML
556 lines
32 KiB
HTML
<!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 -->
|
||
|
||
|
||
<!-- Provide site root and default themes to javascript -->
|
||
<script>
|
||
const path_to_root = "../";
|
||
const default_light_theme = "light";
|
||
const default_dark_theme = "navy";
|
||
</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 {
|
||
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 = 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="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. (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">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">
|
||
<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">
|
||
<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="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>
|
||
<ul>
|
||
<li><a href="#quick-start">Quick Start</a></li>
|
||
<li><a href="#get-the-source-code">Get the source code</a>
|
||
<ul>
|
||
<li><a href="#partial-clone-the-repository">Partial clone the repository</a></li>
|
||
<li><a href="#shallow-clone-the-repository">Shallow clone the repository</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#what-is-xpy">What is <code>x.py</code>?</a>
|
||
<ul>
|
||
<li><a href="#running-xpy">Running <code>x.py</code></a>
|
||
<ul>
|
||
<li><a href="#running-xpy-slightly-more-conveniently">Running <code>x.py</code> slightly more conveniently</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#create-a-bootstraptoml">Create a <code>bootstrap.toml</code></a></li>
|
||
<li><a href="#common-x-commands">Common <code>x</code> commands</a>
|
||
<ul>
|
||
<li><a href="#building-the-compiler">Building the compiler</a></li>
|
||
<li><a href="#build-specific-components">Build specific components</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#creating-a-rustup-toolchain">Creating a rustup toolchain</a></li>
|
||
<li><a href="#building-targets-for-cross-compilation">Building targets for cross-compilation</a></li>
|
||
<li><a href="#other-x-commands">Other <code>x</code> commands</a>
|
||
<ul>
|
||
<li><a href="#cleaning-out-build-directories">Cleaning out build directories</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#remarks-on-disk-space">Remarks on disk space</a></li>
|
||
</ul>
|
||
<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>
|
||
|
||
|
||
</div>
|
||
</body>
|
||
</html>
|