<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>src/bootstrap/README.md - fork/rust @ master</title>
<meta name="description" content="src/bootstrap/README.md in fork/rust at master.">
<meta property="og:title" content="src/bootstrap/README.md - fork/rust @ master">
<meta property="og:description" content="src/bootstrap/README.md in fork/rust at master.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="master" data-tip="3bcad65fbf67b6edf87c949531fbc13435882e6b">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/rust</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/rust</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">bors</span><span class="commit-message" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">Auto merge of #103046 - JanBeh:PR_clarify_cmp_terminology, r=workingjubilee</span><span class="snapshot-sha sha" data-commit="3bcad65fbf67b6edf87c949531fbc13435882e6b">3bcad65fbf6</span><time datetime="2023-10-05T15:24:54+00:00" title="2023-10-05 15:24:54 +0000">2023-10-05</time></p>
<header class="topbar"><details class="switcher"><summary>master</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/rust/ref/master/">master</a><strong>tags</strong><a href="/fork/rust/ref/1.39.0/">1.39.0</a><a href="/fork/rust/ref/1.40.0/">1.40.0</a><a href="/fork/rust/ref/1.41.0/">1.41.0</a><a href="/fork/rust/ref/1.41.1/">1.41.1</a><a href="/fork/rust/ref/1.42.0/">1.42.0</a><a href="/fork/rust/ref/1.43.0/">1.43.0</a><a href="/fork/rust/ref/1.43.1/">1.43.1</a><a href="/fork/rust/ref/1.44.0/">1.44.0</a><a class="all" href="/fork/rust/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/rust/">rust</a> / <a href="/fork/rust/ref/master/tree/src/">src</a> / <a href="/fork/rust/ref/master/tree/src/bootstrap/">bootstrap</a> / <span class="cur">README.md</span></nav>
<span class="view-stats"><span>8.6 KiB</span><span>207 lines</span></span><span class="actions"><a class="raw" href="/fork/rust/raw/e7998a40a6520870b76455bd509da51a5dbe09f8/src/bootstrap/README.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>rustbuild - Bootstrapping Rust</h1>
<p>This README is aimed at helping to explain how Rust is bootstrapped and in general,
some of the technical details of the build system.</p>
<p>Note that this README only covers internal information, not how to use the tool.
Please check <a href="https://rustc-dev-guide.rust-lang.org/building/bootstrapping.html">bootstrapping dev guide</a> for further information.</p>
<h2>Introduction</h2>
<p>The build system defers most of the complicated logic managing invocations
of rustc and rustdoc to Cargo itself. However, moving through various stages
and copying artifacts is still necessary for it to do. Each time rustbuild
is invoked, it will iterate through the list of predefined steps and execute
each serially in turn if it matches the paths passed or is a default rule.
For each step rustbuild relies on the step internally being incremental and
parallel. Note, though, that the <code>-j</code> parameter to rustbuild gets forwarded
to appropriate test harnesses and such.</p>
<h2>Build phases</h2>
<p>The rustbuild build system goes through a few phases to actually build the
compiler. What actually happens when you invoke rustbuild is:</p>
<ol>
<li>The entry point script(<code>x</code> for unix like systems, <code>x.ps1</code> for windows systems,
<code>x.py</code> cross-platform) is run. This script is responsible for downloading the stage0
compiler/Cargo binaries, and it then compiles the build system itself (this folder).
Finally, it then invokes the actual <code>bootstrap</code> binary build system.</li>
<li>In Rust, <code>bootstrap</code> will slurp up all configuration, perform a number of
sanity checks (whether compilers exist, for example), and then start building the
stage0 artifacts.</li>
<li>The stage0 <code>cargo</code>, downloaded earlier, is used to build the standard library
and the compiler, and then these binaries are then copied to the <code>stage1</code>
directory. That compiler is then used to generate the stage1 artifacts which
are then copied to the stage2 directory, and then finally, the stage2
artifacts are generated using that compiler.</li>
</ol>
<p>The goal of each stage is to (a) leverage Cargo as much as possible and failing
that (b) leverage Rust as much as possible!</p>
<h2>Directory Layout</h2>
<p>This build system houses all output under the <code>build</code> directory, which looks
like this:</p>
<pre class="language-bash"><a-c># Root folder of all output. Everything is scoped underneath here</a-c>
<a-f>build/</a-f>

  <a-c># Location where the stage0 compiler downloads are all cached. This directory</a-c>
  <a-c># only contains the tarballs themselves, as they&#39;re extracted elsewhere.</a-c>
  <a-f>cache/</a-f>
    <a-f>2015-12-19/</a-f>
    <a-f>2016-01-15/</a-f>
    <a-f>2016-01-21/</a-f>
    <a-f>...</a-f>

  <a-c># Output directory for building this build system itself. The stage0</a-c>
  <a-c># cargo/rustc are used to build the build system into this location.</a-c>
  <a-f>bootstrap/</a-f>
    <a-f>debug/</a-f>
    <a-f>release/</a-f>

  <a-c># Output of the dist-related steps like dist-std, dist-rustc, and dist-docs</a-c>
  <a-f>dist/</a-f>

  <a-c># Temporary directory used for various input/output as part of various stages</a-c>
  <a-f>tmp/</a-f>

  <a-c># Each remaining directory is scoped by the &quot;host&quot; triple of compilation at</a-c>
  <a-c># hand.</a-c>
  <a-f>x86_64-unknown-linux-gnu/</a-f>

    <a-c># The build artifacts for the `compiler-rt` library for the target that</a-c>
    <a-c># this folder is under. The exact layout here will likely depend on the</a-c>
    <a-c># platform, and this is also built with CMake, so the build system is</a-c>
    <a-c># also likely different.</a-c>
    <a-f>compiler-rt/</a-f>
      <a-f>build/</a-f>

    <a-c># Output folder for LLVM if it is compiled for this target</a-c>
    <a-f>llvm/</a-f>

      <a-c># build folder (e.g. the platform-specific build system). Like with</a-c>
      <a-c># compiler-rt, this is compiled with CMake</a-c>
      <a-f>build/</a-f>

      <a-c># Installation of LLVM. Note that we run the equivalent of &#39;make install&#39;</a-c>
      <a-c># for LLVM, to setup these folders.</a-c>
      <a-f>bin/</a-f>
      <a-f>lib/</a-f>
      <a-f>include/</a-f>
      <a-f>share/</a-f>
      <a-f>...</a-f>

    <a-c># Output folder for all documentation of this target. This is what&#39;s filled</a-c>
    <a-c># in whenever the `doc` step is run.</a-c>
    <a-f>doc/</a-f>

    <a-c># Output for all compiletest-based test suites</a-c>
    <a-f>test/</a-f>
      <a-f>ui/</a-f>
      <a-f>debuginfo/</a-f>
      <a-f>...</a-f>

    <a-c># Location where the stage0 Cargo and Rust compiler are unpacked. This</a-c>
    <a-c># directory is purely an extracted and overlaid tarball of these two (done</a-c>
    <a-c># by the bootstrap python script). In theory, the build system does not</a-c>
    <a-c># modify anything under this directory afterwards.</a-c>
    <a-f>stage0/</a-f>

    <a-c># These to-build directories are the cargo output directories for builds of</a-c>
    <a-c># the standard library and compiler, respectively. Internally, these may also</a-c>
    <a-c># have other target directories, which represent artifacts being compiled</a-c>
    <a-c># from the host to the specified target.</a-c>
    <a-c>#</a-c>
    <a-c># Essentially, each of these directories is filled in by one `cargo`</a-c>
    <a-c># invocation. The build system instruments calling Cargo in the right order</a-c>
    <a-c># with the right variables to ensure that these are filled in correctly.</a-c>
    <a-f>stageN-std/</a-f>
    <a-f>stageN-test/</a-f>
    <a-f>stageN-rustc/</a-f>
    <a-f>stageN-tools/</a-f>

    <a-c># This is a special case of the above directories, **not** filled in via</a-c>
    <a-c># Cargo but rather the build system itself. The stage0 compiler already has</a-c>
    <a-c># a set of target libraries for its own host triple (in its own sysroot)</a-c>
    <a-c># inside of stage0/. When we run the stage0 compiler to bootstrap more</a-c>
    <a-c># things, however, we don&#39;t want to use any of these libraries (as those are</a-c>
    <a-c># the ones that we&#39;re building). So essentially, when the stage1 compiler is</a-c>
    <a-c># being compiled (e.g. after libstd has been built), *this* is used as the</a-c>
    <a-c># sysroot for the stage0 compiler being run.</a-c>
    <a-c>#</a-c>
    <a-c># Basically, this directory is just a temporary artifact used to configure the</a-c>
    <a-c># stage0 compiler to ensure that the libstd that we just built is used to</a-c>
    <a-c># compile the stage1 compiler.</a-c>
    <a-f>stage0-sysroot/lib/</a-f>

    <a-c># These output directories are intended to be standalone working</a-c>
    <a-c># implementations of the compiler (corresponding to each stage). The build</a-c>
    <a-c># system will link (using hard links) output from stageN-{std,rustc} into</a-c>
    <a-c># each of these directories.</a-c>
    <a-c>#</a-c>
    <a-c># In theory these are working rustc sysroot directories, meaning there is</a-c>
    <a-c># no extra build output in these directories.</a-c>
    <a-f>stage1/</a-f>
    <a-f>stage2/</a-f>
    <a-f>stage3/</a-f></pre>
<h2>Extending rustbuild</h2>
<p>When you use the bootstrap system, you'll call it through the entry point script
(<code>x</code>, <code>x.ps1</code>, or <code>x.py</code>). However, most of the code lives in <code>src/bootstrap</code>.
<code>bootstrap</code> has a difficult problem: it is written in Rust, but yet it is run
before the Rust compiler is built! To work around this, there are two components
of bootstrap: the main one written in rust, and <code>bootstrap.py</code>. <code>bootstrap.py</code>
is what gets run by entry point script. It takes care of downloading the <code>stage0</code>
compiler, which will then build the bootstrap binary written in Rust.</p>
<p>Because there are two separate codebases behind <code>x.py</code>, they need to
be kept in sync. In particular, both <code>bootstrap.py</code> and the bootstrap binary
parse <code>config.toml</code> and read the same command line arguments. <code>bootstrap.py</code>
keeps these in sync by setting various environment variables, and the
programs sometimes have to add arguments that are explicitly ignored, to be
read by the other.</p>
<p>Some general areas that you may be interested in modifying are:</p>
<ul>
<li>Adding a new build tool? Take a look at <code>bootstrap/tool.rs</code> for examples of
other tools.</li>
<li>Adding a new compiler crate? Look no further! Adding crates can be done by
adding a new directory with <code>Cargo.toml</code> followed by configuring all
<code>Cargo.toml</code> files accordingly.</li>
<li>Adding a new dependency from crates.io? This should just work inside the
compiler artifacts stage (everything other than libtest and libstd).</li>
<li>Adding a new configuration option? You'll want to modify <code>bootstrap/flags.rs</code>
for command line flags and then <code>bootstrap/config.rs</code> to copy the flags to the
<code>Config</code> struct.</li>
<li>Adding a sanity check? Take a look at <code>bootstrap/sanity.rs</code>.</li>
</ul>
<p>If you make a major change on bootstrap configuration, please remember to:</p>
<ul>
<li>Update <code>CONFIG_CHANGE_HISTORY</code> in <code>src/bootstrap/lib.rs</code>.</li>
</ul>
<ul>
<li>Update <code>change-id = {pull-request-id}</code> in <code>config.example.toml</code>.</li>
</ul>
<p>A 'major change' includes</p>
<ul>
<li>A new option or</li>
<li>A change in the default options.</li>
</ul>
<p>Changes that do not affect contributors to the compiler or users
building rustc from source don't need an update to <code>CONFIG_CHANGE_HISTORY</code>.</p>
<p>If you have any questions, feel free to reach out on the <code>#t-infra/bootstrap</code> channel
at <a href="https://rust-lang.zulipchat.com/#narrow/stream/t-infra.2Fbootstrap">Rust Bootstrap Zulip server</a>. When you encounter bugs,
please file issues on the <a href="https://github.com/rust-lang/rust/issues">Rust issue tracker</a>.</p>
<h2>Changelog</h2>
<p>Because we do not release bootstrap with versions, we also do not maintain CHANGELOG files. To
review the changes made to bootstrap, simply run <code>git log --no-merges --oneline -- src/bootstrap</code>.</p>
</section><div class="code-panel"><pre class="code src" data-hl="src/bootstrap/README.md"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"># rustbuild - Bootstrapping Rust</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">This README is aimed at helping to explain how Rust is bootstrapped and in general,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text">some of the technical details of the build system.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">Note that this README only covers internal information, not how to use the tool.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">Please check [bootstrapping dev guide][bootstrapping-dev-guide] for further information.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">[bootstrapping-dev-guide]: https://rustc-dev-guide.rust-lang.org/building/bootstrapping.html</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">## Introduction</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text">The build system defers most of the complicated logic managing invocations</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">of rustc and rustdoc to Cargo itself. However, moving through various stages</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">and copying artifacts is still necessary for it to do. Each time rustbuild</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text">is invoked, it will iterate through the list of predefined steps and execute</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">each serially in turn if it matches the paths passed or is a default rule.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text">For each step rustbuild relies on the step internally being incremental and</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">parallel. Note, though, that the `-j` parameter to rustbuild gets forwarded</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">to appropriate test harnesses and such.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text">## Build phases</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">The rustbuild build system goes through a few phases to actually build the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text">compiler. What actually happens when you invoke rustbuild is:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">1. The entry point script(`x` for unix like systems, `x.ps1` for windows systems,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">   `x.py` cross-platform) is run. This script is responsible for downloading the stage0</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">   compiler/Cargo binaries, and it then compiles the build system itself (this folder).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text">   Finally, it then invokes the actual `bootstrap` binary build system.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text">2. In Rust, `bootstrap` will slurp up all configuration, perform a number of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text">   sanity checks (whether compilers exist, for example), and then start building the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text">   stage0 artifacts.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text">3. The stage0 `cargo`, downloaded earlier, is used to build the standard library</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text">   and the compiler, and then these binaries are then copied to the `stage1`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text">   directory. That compiler is then used to generate the stage1 artifacts which</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text">   are then copied to the stage2 directory, and then finally, the stage2</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text">   artifacts are generated using that compiler.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text">The goal of each stage is to (a) leverage Cargo as much as possible and failing</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text">that (b) leverage Rust as much as possible!</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text">## Directory Layout</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text">This build system houses all output under the `build` directory, which looks</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text">like this:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text">```sh</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"># Root folder of all output. Everything is scoped underneath here</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text">build/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text">  # Location where the stage0 compiler downloads are all cached. This directory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text">  # only contains the tarballs themselves, as they're extracted elsewhere.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text">  cache/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text">    2015-12-19/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text">    2016-01-15/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text">    2016-01-21/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text">    ...</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text">  # Output directory for building this build system itself. The stage0</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text">  # cargo/rustc are used to build the build system into this location.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text">  bootstrap/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text">    debug/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text">    release/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text">  # Output of the dist-related steps like dist-std, dist-rustc, and dist-docs</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text">  dist/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text">  # Temporary directory used for various input/output as part of various stages</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text">  tmp/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text">  # Each remaining directory is scoped by the &quot;host&quot; triple of compilation at</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text">  # hand.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text">  x86_64-unknown-linux-gnu/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text">    # The build artifacts for the `compiler-rt` library for the target that</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text">    # this folder is under. The exact layout here will likely depend on the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text">    # platform, and this is also built with CMake, so the build system is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text">    # also likely different.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text">    compiler-rt/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text">      build/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text">    # Output folder for LLVM if it is compiled for this target</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text">    llvm/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text">      # build folder (e.g. the platform-specific build system). Like with</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text">      # compiler-rt, this is compiled with CMake</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text">      build/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text">      # Installation of LLVM. Note that we run the equivalent of 'make install'</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text">      # for LLVM, to setup these folders.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text">      bin/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text">      lib/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text">      include/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text">      share/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text">      ...</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text">    # Output folder for all documentation of this target. This is what's filled</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text">    # in whenever the `doc` step is run.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text">    doc/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text">    # Output for all compiletest-based test suites</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text">    test/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text">      ui/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text">      debuginfo/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text">      ...</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text">    # Location where the stage0 Cargo and Rust compiler are unpacked. This</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text">    # directory is purely an extracted and overlaid tarball of these two (done</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text">    # by the bootstrap python script). In theory, the build system does not</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text">    # modify anything under this directory afterwards.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text">    stage0/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text">    # These to-build directories are the cargo output directories for builds of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text">    # the standard library and compiler, respectively. Internally, these may also</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text">    # have other target directories, which represent artifacts being compiled</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text">    # from the host to the specified target.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text">    #</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text">    # Essentially, each of these directories is filled in by one `cargo`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text">    # invocation. The build system instruments calling Cargo in the right order</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text">    # with the right variables to ensure that these are filled in correctly.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text">    stageN-std/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text">    stageN-test/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text">    stageN-rustc/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text">    stageN-tools/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text">    # This is a special case of the above directories, **not** filled in via</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text">    # Cargo but rather the build system itself. The stage0 compiler already has</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text">    # a set of target libraries for its own host triple (in its own sysroot)</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text">    # inside of stage0/. When we run the stage0 compiler to bootstrap more</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text">    # things, however, we don't want to use any of these libraries (as those are</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text">    # the ones that we're building). So essentially, when the stage1 compiler is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text">    # being compiled (e.g. after libstd has been built), *this* is used as the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text">    # sysroot for the stage0 compiler being run.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text">    #</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text">    # Basically, this directory is just a temporary artifact used to configure the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text">    # stage0 compiler to ensure that the libstd that we just built is used to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text">    # compile the stage1 compiler.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L139" href="#L139">139</a><span class="code-text">    stage0-sysroot/lib/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L140" href="#L140">140</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L141" href="#L141">141</a><span class="code-text">    # These output directories are intended to be standalone working</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L142" href="#L142">142</a><span class="code-text">    # implementations of the compiler (corresponding to each stage). The build</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L143" href="#L143">143</a><span class="code-text">    # system will link (using hard links) output from stageN-{std,rustc} into</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L144" href="#L144">144</a><span class="code-text">    # each of these directories.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L145" href="#L145">145</a><span class="code-text">    #</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L146" href="#L146">146</a><span class="code-text">    # In theory these are working rustc sysroot directories, meaning there is</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L147" href="#L147">147</a><span class="code-text">    # no extra build output in these directories.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L148" href="#L148">148</a><span class="code-text">    stage1/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L149" href="#L149">149</a><span class="code-text">    stage2/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L150" href="#L150">150</a><span class="code-text">    stage3/</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L151" href="#L151">151</a><span class="code-text">```</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L152" href="#L152">152</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L153" href="#L153">153</a><span class="code-text">## Extending rustbuild</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L154" href="#L154">154</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L155" href="#L155">155</a><span class="code-text">When you use the bootstrap system, you'll call it through the entry point script</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L156" href="#L156">156</a><span class="code-text">(`x`, `x.ps1`, or `x.py`). However, most of the code lives in `src/bootstrap`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L157" href="#L157">157</a><span class="code-text">`bootstrap` has a difficult problem: it is written in Rust, but yet it is run</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L158" href="#L158">158</a><span class="code-text">before the Rust compiler is built! To work around this, there are two components</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L159" href="#L159">159</a><span class="code-text">of bootstrap: the main one written in rust, and `bootstrap.py`. `bootstrap.py`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L160" href="#L160">160</a><span class="code-text">is what gets run by entry point script. It takes care of downloading the `stage0`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L161" href="#L161">161</a><span class="code-text">compiler, which will then build the bootstrap binary written in Rust.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L162" href="#L162">162</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L163" href="#L163">163</a><span class="code-text">Because there are two separate codebases behind `x.py`, they need to</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L164" href="#L164">164</a><span class="code-text">be kept in sync. In particular, both `bootstrap.py` and the bootstrap binary</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L165" href="#L165">165</a><span class="code-text">parse `config.toml` and read the same command line arguments. `bootstrap.py`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L166" href="#L166">166</a><span class="code-text">keeps these in sync by setting various environment variables, and the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L167" href="#L167">167</a><span class="code-text">programs sometimes have to add arguments that are explicitly ignored, to be</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L168" href="#L168">168</a><span class="code-text">read by the other.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L169" href="#L169">169</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L170" href="#L170">170</a><span class="code-text">Some general areas that you may be interested in modifying are:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L171" href="#L171">171</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L172" href="#L172">172</a><span class="code-text">* Adding a new build tool? Take a look at `bootstrap/tool.rs` for examples of</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L173" href="#L173">173</a><span class="code-text">  other tools.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L174" href="#L174">174</a><span class="code-text">* Adding a new compiler crate? Look no further! Adding crates can be done by</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L175" href="#L175">175</a><span class="code-text">  adding a new directory with `Cargo.toml` followed by configuring all</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L176" href="#L176">176</a><span class="code-text">  `Cargo.toml` files accordingly.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L177" href="#L177">177</a><span class="code-text">* Adding a new dependency from crates.io? This should just work inside the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L178" href="#L178">178</a><span class="code-text">  compiler artifacts stage (everything other than libtest and libstd).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L179" href="#L179">179</a><span class="code-text">* Adding a new configuration option? You'll want to modify `bootstrap/flags.rs`</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L180" href="#L180">180</a><span class="code-text">  for command line flags and then `bootstrap/config.rs` to copy the flags to the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L181" href="#L181">181</a><span class="code-text">  `Config` struct.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L182" href="#L182">182</a><span class="code-text">* Adding a sanity check? Take a look at `bootstrap/sanity.rs`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L183" href="#L183">183</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L184" href="#L184">184</a><span class="code-text">If you make a major change on bootstrap configuration, please remember to:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L185" href="#L185">185</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L186" href="#L186">186</a><span class="code-text">+ Update `CONFIG_CHANGE_HISTORY` in `src/bootstrap/lib.rs`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L187" href="#L187">187</a><span class="code-text">* Update `change-id = {pull-request-id}` in `config.example.toml`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L188" href="#L188">188</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L189" href="#L189">189</a><span class="code-text">A 'major change' includes</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L190" href="#L190">190</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L191" href="#L191">191</a><span class="code-text">* A new option or</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L192" href="#L192">192</a><span class="code-text">* A change in the default options.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L193" href="#L193">193</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L194" href="#L194">194</a><span class="code-text">Changes that do not affect contributors to the compiler or users</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L195" href="#L195">195</a><span class="code-text">building rustc from source don't need an update to `CONFIG_CHANGE_HISTORY`.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L196" href="#L196">196</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L197" href="#L197">197</a><span class="code-text">If you have any questions, feel free to reach out on the `#t-infra/bootstrap` channel</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L198" href="#L198">198</a><span class="code-text">at [Rust Bootstrap Zulip server][rust-bootstrap-zulip]. When you encounter bugs,</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L199" href="#L199">199</a><span class="code-text">please file issues on the [Rust issue tracker][rust-issue-tracker].</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L200" href="#L200">200</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L201" href="#L201">201</a><span class="code-text">[rust-bootstrap-zulip]: https://rust-lang.zulipchat.com/#narrow/stream/t-infra.2Fbootstrap</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L202" href="#L202">202</a><span class="code-text">[rust-issue-tracker]: https://github.com/rust-lang/rust/issues</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L203" href="#L203">203</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L204" href="#L204">204</a><span class="code-text">## Changelog</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L205" href="#L205">205</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L206" href="#L206">206</a><span class="code-text">Because we do not release bootstrap with versions, we also do not maintain CHANGELOG files. To</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L207" href="#L207">207</a><span class="code-text">review the changes made to bootstrap, simply run `git log --no-merges --oneline -- src/bootstrap`.</span></span></pre></div></div>
</main>
</body>
</html>
